tempest-fastapi-sdk 0.35.0__tar.gz → 0.37.0__tar.gz

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/CHANGELOG.md

@@ -5,6 +5,125 @@ 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.37.0] — 2026-06-07
+
+### Added
+
+- **`[sqlite]` and `[postgres]` install extras** for the async database
+  drivers. The SDK keeps `sqlalchemy[asyncio]` as a core dependency but
+  ships **no DBAPI driver by default** — the driver is a deploy choice.
+  Install `tempest-fastapi-sdk[sqlite]` (`aiosqlite`, dev default) or
+  `[postgres]` (`asyncpg`, production); both are bundled into `[all]`.
+  Without one, the engine raised `ModuleNotFoundError` on first
+  connection.
+
+### Changed
+
+- **`tempest new` scaffold now ships a working DB driver.** The generated
+  `pyproject.toml` pins `aiosqlite` as a **runtime** dependency (it was
+  previously dev-only, so the default SQLite URL failed under a no-dev
+  install) and carries a commented `asyncpg` line next to it, ready to
+  uncomment when switching `DATABASE_URL` to PostgreSQL — matching the
+  commented Postgres URL already in `.env.example`.
+
+- **`tempest new` / `tempest generate --docker`: credentials now resolve
+  from `.env`, not hardcoded in the compose.** Every `environment:` block
+  in the generated `docker-compose.yaml` now uses the `${VAR:-default}`
+  form so Docker Compose reads the value from the `.env` next to the
+  compose file, keeping secrets out of a VCS-tracked compose. The
+  `:-default` preserves zero-config dev boot before `.env.example` is
+  copied to `.env`. Affected variables: `POSTGRES_USER` /
+  `POSTGRES_PASSWORD` / `POSTGRES_DB`, `RABBITMQ_DEFAULT_USER` /
+  `RABBITMQ_DEFAULT_PASS` / `RABBITMQ_DEFAULT_VHOST`, `MINIO_ROOT_USER` /
+  `MINIO_ROOT_PASSWORD` (plus the MinIO bootstrap container's `mc alias`).
+  `env_block_for` now emits these credential keys into `.env.example` so
+  the generated `.env` carries them with their defaults.
+
+## [0.36.0] — 2026-06-06
+
+Admin panel brought to Django-admin parity: the list view, write CRUD,
+bulk actions, dashboard, login, and audit trail all landed across the
+phases below.
+
+### Added
+
+- **Admin list view — Phase 1 (read-only enhancements + responsive).**
+    - Clickable **column sorting** on the list view
+      (`?sort=<column>&dir=asc|desc`), validated against the displayed
+      real columns; the admin's configured `ordering` remains the
+      default.
+    - **CSV / JSON export** endpoint
+      (`GET /admin/m/{slug}/export.csv` / `.json`) honoring the active
+      search / filters / sort. New `make_admin_router(export_max_rows=…)`
+      caps export size (default 5000).
+    - **Responsive admin UI** — bundled templates + CSS now adapt to
+      mobile (≤600px): stacked header, full-width search/filters/actions,
+      horizontal-scroll table wrappers, single-column detail grid.
+      Verified at 390px (mobile) and 1280px (desktop).
+
+- **Admin write CRUD — Phase 2a (create / edit / delete).**
+    - `GET/POST /admin/m/{slug}/new` (create), `GET/POST
+      /admin/m/{slug}/{identity}/edit` (edit), and `POST
+      /admin/m/{slug}/{identity}/delete` (delete), each gated by new
+      `AdminModel(can_create=…, can_edit=…, can_delete=…)` flags
+      (default `True`; a disabled view returns `404`).
+    - **CSRF-protected** mutations — every write form carries the
+      session CSRF token, verified server-side (`403` on mismatch).
+    - **Type-aware field widgets** — text / textarea (long strings) /
+      number / checkbox / `datetime-local` / date / enum `select`,
+      derived from the column types, with required-field + per-field
+      validation errors re-rendered on the form, and integrity errors
+      surfaced inline.
+    - Detail view gains Edit / Delete controls; list view gains a
+      "+ New" button. All responsive (verified at 390px / 1280px).
+
+- **Admin bulk actions — Phase 2b.**
+    - List view gains row checkboxes + a select-all toggle and a bulk
+      action bar. `POST /admin/m/{slug}/bulk` applies **delete**
+      (`can_delete`), **activate** / **deactivate** (`can_edit`, toggling
+      the `is_active` flag) to the selected rows, CSRF-verified.
+      Backed by `BaseRepository.delete_batch` / `bulk_update`.
+      Responsive (verified at 390px / 1280px).
+
+- **Admin foreign-key select — Phase 2c.**
+    - A foreign-key column whose referenced table has its own
+      `AdminModel` now renders as a **dropdown of the related rows**
+      (Django's FK select) on the create/edit form, instead of a raw
+      UUID input. Option labels come from the referenced admin's first
+      `search_fields` entry (falling back to a `name`/`title`/`email`
+      attribute, then the id). Capped at 1000 rows. FKs to unmanaged
+      tables stay plain UUID inputs.
+
+- **Admin dashboard — counts + metrics (Phase 3a).**
+    - The dashboard now renders each registered model as a card with its
+      **live row count** and Browse / + New links, plus a **system
+      metrics panel** (CPU / RAM / disk) via `MetricsUtils`. The panel
+      is on by default, silently omitted when the `[metrics]` extra is
+      absent, and disabled with `make_admin_router(show_metrics=False)`.
+      Responsive card grids (verified at 390px / 1280px).
+
+- **Admin MFA login — Phase 3b.**
+    - The admin login now supports a TOTP second factor. After the
+      password step, a principal with MFA enabled gets a short
+      `mfa_pending` session and is redirected to `GET/POST /admin/mfa`
+      (a CSRF-protected TOTP challenge); only a valid code upgrades the
+      session to full access. `AdminAuthBackend` gains `mfa_enabled` /
+      `verify_mfa` (default off); `UserModelAuthBackend` implements them
+      against `MFAMixin`'s `totp_secret` / `totp_enabled_at` via
+      `TOTPHelper` (new `mfa_issuer` / `mfa_window` ctor args). Pending
+      sessions are denied every admin page until the challenge passes.
+
+- **Admin audit trail — Phase 3c.**
+    - Create/edit through the admin now **stamps** `created_by` /
+      `updated_by` (from `AuditMixin`) with the acting admin's id. The
+      detail view gained an **Audit panel** showing created/updated
+      timestamps and — when the model has the audit columns — the actor,
+      with the stored UUID resolved to a display name via the auth
+      backend. Models without `AuditMixin` show the timestamps only.
+
+    File-upload widget and inline/related editing remain tracked as later
+    admin phases on the roadmap.
+
 ## [0.35.0] — 2026-06-06
 
 ### Added

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.35.0
+Version: 0.37.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
@@ -32,6 +32,8 @@ Requires-Dist: jinja2>=3.1.0; extra == 'admin'
 Provides-Extra: all
 Requires-Dist: aiofiles>=24.1.0; extra == 'all'
 Requires-Dist: aiosmtplib>=4.0.0; extra == 'all'
+Requires-Dist: aiosqlite>=0.20.0; extra == 'all'
+Requires-Dist: asyncpg>=0.30.0; extra == 'all'
 Requires-Dist: bcrypt>=5.0.0; extra == 'all'
 Requires-Dist: cryptography>=42.0.0; extra == 'all'
 Requires-Dist: email-validator>=2.0.0; extra == 'all'
@@ -68,10 +70,14 @@ Provides-Extra: mfa
 Requires-Dist: pyotp>=2.9.0; extra == 'mfa'
 Provides-Extra: minio
 Requires-Dist: minio>=7.2.0; extra == 'minio'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
 Provides-Extra: prometheus
 Requires-Dist: prometheus-client>=0.20.0; extra == 'prometheus'
 Provides-Extra: queue
 Requires-Dist: faststream[rabbit]>=0.5.30; extra == 'queue'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20.0; extra == 'sqlite'
 Provides-Extra: tasks
 Requires-Dist: taskiq-aio-pika>=0.4.0; extra == 'tasks'
 Requires-Dist: taskiq>=0.11.0; extra == 'tasks'
@@ -174,7 +180,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.35.0",
+    "tempest-fastapi-sdk>=0.37.0",
 ]
 ```
 
@@ -199,13 +205,18 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
+| `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
 | `[all]` | everything above | every helper |
 
 ```bash
 pip install "tempest-fastapi-sdk[auth,upload]"   # only what the service uses
-pip install "tempest-fastapi-sdk[all]"           # or pull everything
+pip install "tempest-fastapi-sdk[postgres]"       # add the async DB driver you deploy with
+pip install "tempest-fastapi-sdk[all]"            # or pull everything
 ```
 
+> **The SDK ships no database driver by default.** `sqlalchemy[asyncio]` is core, but the async DBAPI is your deploy choice — add `[sqlite]` (`aiosqlite`, dev default) or `[postgres]` (`asyncpg`, production). Without one, the engine raises `ModuleNotFoundError` for the driver on first connection. Services scaffolded with `tempest new` already pin `aiosqlite` and carry a commented `asyncpg` line in `pyproject.toml`.
+
 Since `0.7.1` every optional dependency is imported lazily at first instantiation, so `import tempest_fastapi_sdk` works with any subset of extras — instantiating a helper whose extra is missing raises `ImportError` with a clear hint pointing at the right one.
 
 ---
@@ -3403,7 +3414,7 @@ tempest user list --admin                             # admins only
 
 ### Admin site recipe
 
-Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. Phase 1 ships read-only views; create/edit/delete land in 0.14.0 and inline + bulk actions in 0.15.0.
+Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / per-field filters / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: file upload and inline/related editing.
 
 Requires the `[admin]` extra:
 
@@ -3522,11 +3533,19 @@ app.include_router(
 `make_admin_router` mounts:
 
 - `GET  /admin/login`, `POST /admin/login`, `POST /admin/logout` — auth flow.
-- `GET  /admin/` — dashboard listing every registered admin.
-- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`).
-- `GET  /admin/m/{slug}/{identity}` — read-only detail view.
+- `GET/POST /admin/mfa` — TOTP challenge (second factor) between password and access, for principals with MFA enabled.
+- `GET  /admin/` — dashboard: a card per model with **row count** + Browse/New, plus a **metrics panel** (CPU/RAM/disk via `MetricsUtils`; on by default, omitted without the `[metrics]` extra, disabled with `make_admin_router(show_metrics=False)`).
+- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`) + clickable **column sorting** (`?sort=<column>&dir=asc|desc`).
+- `GET  /admin/m/{slug}/export.csv` / `export.json` — **export** the current result set (honoring search/filters/sort) as CSV or JSON (row cap via `make_admin_router(export_max_rows=…)`, default 5000).
+- `POST /admin/m/{slug}/bulk` — **bulk actions** (delete / activate / deactivate) on selected rows.
+- `GET/POST /admin/m/{slug}/new` — **create** a record (when `can_create`).
+- `GET  /admin/m/{slug}/{identity}` — detail view with Edit/Delete buttons + an Audit panel.
+- `GET/POST /admin/m/{slug}/{identity}/edit` — **edit** a record (when `can_edit`).
+- `POST /admin/m/{slug}/{identity}/delete` — **delete** a record (when `can_delete`).
 - `GET  /admin/static/{path}` — bundled CSS/HTMX assets.
 
+Write operations (create/edit/delete/bulk) are gated by the `AdminModel` flags `can_create` / `can_edit` / `can_delete` (all `True` by default; a disabled view returns `404`), carry a per-session CSRF token validated server-side, derive form widgets from the column type, render an FK-select dropdown for foreign keys whose target has a registered `AdminModel`, and stamp `created_by` / `updated_by` (from `AuditMixin`) with the acting admin's id.
+
 #### 4. Session security defaults
 
 `SignedCookieSessionStore` uses `itsdangerous.TimestampSigner` (HMAC-SHA256) to sign a single cookie:
@@ -3535,7 +3554,7 @@ app.include_router(
 - `Secure` flagged when `cookie_secure=True` (default; flip off in local HTTP dev).
 - `SameSite=Lax` (`"lax"`/`"strict"`/`"none"` accepted).
 - Default lifetime `8h`; expired or tampered cookies are rejected silently.
-- Per-session CSRF token is generated at login and required by every form POST (only `logout` in Phase 1).
+- Per-session CSRF token is generated at login and required by every form POST (login, logout, create, edit, delete, bulk actions).
 - `secret_key` must be at least 32 bytes — short keys raise `ValueError` at construction time.
 
 #### 5. Plug in a custom auth backend

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/README.md

@@ -89,7 +89,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.35.0",
+    "tempest-fastapi-sdk>=0.37.0",
 ]
 ```
 
@@ -114,13 +114,18 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
+| `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
 | `[all]` | everything above | every helper |
 
 ```bash
 pip install "tempest-fastapi-sdk[auth,upload]"   # only what the service uses
-pip install "tempest-fastapi-sdk[all]"           # or pull everything
+pip install "tempest-fastapi-sdk[postgres]"       # add the async DB driver you deploy with
+pip install "tempest-fastapi-sdk[all]"            # or pull everything
 ```
 
+> **The SDK ships no database driver by default.** `sqlalchemy[asyncio]` is core, but the async DBAPI is your deploy choice — add `[sqlite]` (`aiosqlite`, dev default) or `[postgres]` (`asyncpg`, production). Without one, the engine raises `ModuleNotFoundError` for the driver on first connection. Services scaffolded with `tempest new` already pin `aiosqlite` and carry a commented `asyncpg` line in `pyproject.toml`.
+
 Since `0.7.1` every optional dependency is imported lazily at first instantiation, so `import tempest_fastapi_sdk` works with any subset of extras — instantiating a helper whose extra is missing raises `ImportError` with a clear hint pointing at the right one.
 
 ---
@@ -3318,7 +3323,7 @@ tempest user list --admin                             # admins only
 
 ### Admin site recipe
 
-Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. Phase 1 ships read-only views; create/edit/delete land in 0.14.0 and inline + bulk actions in 0.15.0.
+Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / per-field filters / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: file upload and inline/related editing.
 
 Requires the `[admin]` extra:
 
@@ -3437,11 +3442,19 @@ app.include_router(
 `make_admin_router` mounts:
 
 - `GET  /admin/login`, `POST /admin/login`, `POST /admin/logout` — auth flow.
-- `GET  /admin/` — dashboard listing every registered admin.
-- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`).
-- `GET  /admin/m/{slug}/{identity}` — read-only detail view.
+- `GET/POST /admin/mfa` — TOTP challenge (second factor) between password and access, for principals with MFA enabled.
+- `GET  /admin/` — dashboard: a card per model with **row count** + Browse/New, plus a **metrics panel** (CPU/RAM/disk via `MetricsUtils`; on by default, omitted without the `[metrics]` extra, disabled with `make_admin_router(show_metrics=False)`).
+- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`) + clickable **column sorting** (`?sort=<column>&dir=asc|desc`).
+- `GET  /admin/m/{slug}/export.csv` / `export.json` — **export** the current result set (honoring search/filters/sort) as CSV or JSON (row cap via `make_admin_router(export_max_rows=…)`, default 5000).
+- `POST /admin/m/{slug}/bulk` — **bulk actions** (delete / activate / deactivate) on selected rows.
+- `GET/POST /admin/m/{slug}/new` — **create** a record (when `can_create`).
+- `GET  /admin/m/{slug}/{identity}` — detail view with Edit/Delete buttons + an Audit panel.
+- `GET/POST /admin/m/{slug}/{identity}/edit` — **edit** a record (when `can_edit`).
+- `POST /admin/m/{slug}/{identity}/delete` — **delete** a record (when `can_delete`).
 - `GET  /admin/static/{path}` — bundled CSS/HTMX assets.
 
+Write operations (create/edit/delete/bulk) are gated by the `AdminModel` flags `can_create` / `can_edit` / `can_delete` (all `True` by default; a disabled view returns `404`), carry a per-session CSRF token validated server-side, derive form widgets from the column type, render an FK-select dropdown for foreign keys whose target has a registered `AdminModel`, and stamp `created_by` / `updated_by` (from `AuditMixin`) with the acting admin's id.
+
 #### 4. Session security defaults
 
 `SignedCookieSessionStore` uses `itsdangerous.TimestampSigner` (HMAC-SHA256) to sign a single cookie:
@@ -3450,7 +3463,7 @@ app.include_router(
 - `Secure` flagged when `cookie_secure=True` (default; flip off in local HTTP dev).
 - `SameSite=Lax` (`"lax"`/`"strict"`/`"none"` accepted).
 - Default lifetime `8h`; expired or tampered cookies are rejected silently.
-- Per-session CSRF token is generated at login and required by every form POST (only `logout` in Phase 1).
+- Per-session CSRF token is generated at login and required by every form POST (login, logout, create, edit, delete, bulk actions).
 - `secret_key` must be at least 32 bytes — short keys raise `ValueError` at construction time.
 
 #### 5. Plug in a custom auth backend

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/installation.en.md

@@ -29,6 +29,9 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[minio]` | `minio` | `AsyncMinIOClient`, `MinIOUploadStorage` |
 | `[http]` | `httpx` | `HTTPClient` + `RetryPolicy` + circuit-breaker |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
+| `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA (TOTP) endpoints on the bundled auth flow |
+| `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
+| `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
 | `[all]` | everything above | every helper |
 
 === "Subset (recommended)"
@@ -46,17 +49,25 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 === "uv add"
 
     ```bash
-    uv add "tempest-fastapi-sdk[auth,upload]>=0.32.0"
+    uv add "tempest-fastapi-sdk[auth,upload,postgres]>=0.37.0"
     ```
 
 === "pyproject.toml"
 
     ```toml
     dependencies = [
-        "tempest-fastapi-sdk[auth,upload]>=0.32.0",
+        "tempest-fastapi-sdk[auth,upload,postgres]>=0.37.0",
     ]
     ```
 
+!!! warning "The SDK ships no database driver by default"
+    `sqlalchemy[asyncio]` is core, but the async DBAPI is your deploy
+    choice: install `[sqlite]` (`aiosqlite`, dev default) or `[postgres]`
+    (`asyncpg`, production). Without one, the engine raises
+    `ModuleNotFoundError` for the driver on first connection. Services
+    scaffolded with `tempest new` already pin `aiosqlite` and carry a
+    commented `asyncpg` line in `pyproject.toml`.
+
 !!! info "Lazy imports"
     Since 0.7.1 every optional dependency is imported lazily at first instantiation, so `import tempest_fastapi_sdk` works even when only a subset of extras is installed. Instantiating a helper whose extra is missing raises `ImportError` with a clear hint pointing at the right extra.
 

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/installation.md

@@ -29,6 +29,9 @@ Os helpers mais ricos puxam dependências de terceiros que só são necessárias
 | `[minio]` | `minio` | `AsyncMinIOClient`, `MinIOUploadStorage` |
 | `[http]` | `httpx` | `HTTPClient` + `RetryPolicy` + circuit-breaker |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
+| `[mfa]` | `pyotp` | `TOTPHelper` + endpoints MFA/2FA (TOTP) do fluxo bundled de auth |
+| `[sqlite]` | `aiosqlite` | driver async SQLite para URLs `sqlite+aiosqlite://` (default de dev) |
+| `[postgres]` | `asyncpg` | driver async PostgreSQL para URLs `postgresql+asyncpg://` (produção) |
 | `[all]` | tudo acima | todos os helpers |
 
 === "Subconjunto (recomendado)"
@@ -46,17 +49,25 @@ Os helpers mais ricos puxam dependências de terceiros que só são necessárias
 === "uv add"
 
     ```bash
-    uv add "tempest-fastapi-sdk[auth,upload]>=0.32.0"
+    uv add "tempest-fastapi-sdk[auth,upload,postgres]>=0.37.0"
     ```
 
 === "pyproject.toml"
 
     ```toml
     dependencies = [
-        "tempest-fastapi-sdk[auth,upload]>=0.32.0",
+        "tempest-fastapi-sdk[auth,upload,postgres]>=0.37.0",
     ]
     ```
 
+!!! warning "O SDK não traz driver de banco por padrão"
+    `sqlalchemy[asyncio]` é dependência core, mas o DBAPI async é escolha
+    do seu deploy: instale `[sqlite]` (`aiosqlite`, default de dev) ou
+    `[postgres]` (`asyncpg`, produção). Sem nenhum, o engine levanta
+    `ModuleNotFoundError` do driver na primeira conexão. Serviços
+    criados com `tempest new` já pinam `aiosqlite` e carregam uma linha
+    `asyncpg` comentada no `pyproject.toml`.
+
 !!! info "Imports preguiçosos"
     Desde a 0.7.1 toda dependência opcional é importada de forma preguiçosa na primeira instanciação, então `import tempest_fastapi_sdk` funciona mesmo quando só um subconjunto de extras está instalado. Instanciar um helper cujo extra está faltando levanta `ImportError` com uma dica clara apontando para o extra certo.
 

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/recipes/admin.en.md

@@ -1,7 +1,7 @@
 # Admin site
 
 
-Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. Phase 1 ships read-only views; create/edit/delete land in 0.14.0 and inline + bulk actions in 0.15.0.
+Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / per-field filters / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: file upload and inline/related editing.
 
 Requires the `[admin]` extra:
 
@@ -120,11 +120,33 @@ app.include_router(
 `make_admin_router` mounts:
 
 - `GET  /admin/login`, `POST /admin/login`, `POST /admin/logout` — auth flow.
-- `GET  /admin/` — dashboard listing every registered admin.
-- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`).
-- `GET  /admin/m/{slug}/{identity}` — read-only detail view.
+- `GET/POST /admin/mfa` — TOTP second-factor challenge between the password step and access, for MFA-enabled principals.
+- `GET  /admin/` — dashboard: a card per model with its **live row count** + Browse/New, plus a **metrics panel** (CPU/RAM/disk via `MetricsUtils`). On by default, omitted without the `[metrics]` extra, disable with `make_admin_router(show_metrics=False)`.
+- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`) + clickable **column sorting** (`?sort=<column>&dir=asc|desc`).
+- `GET  /admin/m/{slug}/export.csv` / `export.json` — **export** the current result set (honoring search/filters/sort) as CSV or JSON. Row cap via `make_admin_router(export_max_rows=…)` (default 5000).
+- `POST /admin/m/{slug}/bulk` — **bulk actions** (delete / activate / deactivate) on the selected rows.
+- `GET/POST /admin/m/{slug}/new` — **create** a record (when `can_create`).
+- `GET  /admin/m/{slug}/{identity}` — detail view with Edit/Delete controls.
+- `GET/POST /admin/m/{slug}/{identity}/edit` — **edit** a record (when `can_edit`).
+- `POST /admin/m/{slug}/{identity}/delete` — **delete** a record (when `can_delete`).
 - `GET  /admin/static/{path}` — bundled CSS/HTMX assets.
 
+!!! info "Write CRUD + permissions"
+    Create/edit/delete are gated by `AdminModel` flags: `can_create` / `can_edit` / `can_delete` (all `True` by default; a disabled view returns `404`). Every write POST carries the session CSRF token, verified server-side (`403` on mismatch). **Field widgets** are derived from the column type — text / textarea (long strings) / number / checkbox / `datetime-local` / date / `select` for enums — with required-field + per-field validation errors re-rendered on the form.
+
+    **Bulk actions**: the list view shows per-row checkboxes + select-all and an action bar (delete / activate / deactivate) operating on the checked rows via `POST .../bulk` (CSRF + `can_delete`/`can_edit` flags), backed by `BaseRepository.delete_batch` / `bulk_update`.
+
+    **FK-select**: a foreign-key column whose target has a registered `AdminModel` renders as a dropdown of the related rows (like Django's FK select) on the form, instead of a raw UUID input. The option label comes from the referenced admin's first `search_fields` entry (fallback: a `name`/`title`/`email` attribute, then the id). Capped at 1000 rows; FKs to unmanaged tables stay UUID inputs.
+
+    **MFA login**: a principal with MFA enabled (`MFAMixin`'s `totp_secret`/`totp_enabled_at`) goes through a TOTP challenge at `/admin/mfa` after the password — only a valid code grants access. Enable it via `UserModelAuthBackend(UserModel, mfa_issuer=...)`; custom backends override `mfa_enabled`/`verify_mfa`.
+
+    **Audit trail**: create/edit through the admin stamps `created_by`/`updated_by` (from `AuditMixin`) with the acting admin's id; the detail view shows an **Audit** panel with timestamps and — when the model has the audit columns — the actor (UUID resolved to a display name via the auth backend). Models without `AuditMixin` show timestamps only.
+
+    Not yet included (later roadmap phases): file upload, inline/related editing.
+
+!!! tip "Responsive by default"
+    The bundled templates + CSS are responsive: on narrow screens (≤600px) the header stacks, search/filters/actions go full-width, tables get horizontal scroll (never breaking the layout), and the detail grid collapses to a single column. Column headers are clickable to toggle sort order (▲/▼).
+
 #### 4. Session security defaults
 
 `SignedCookieSessionStore` uses `itsdangerous.TimestampSigner` (HMAC-SHA256) to sign a single cookie:
@@ -133,7 +155,7 @@ app.include_router(
 - `Secure` flagged when `cookie_secure=True` (default; flip off in local HTTP dev).
 - `SameSite=Lax` (`"lax"`/`"strict"`/`"none"` accepted).
 - Default lifetime `8h`; expired or tampered cookies are rejected silently.
-- Per-session CSRF token is generated at login and required by every form POST (only `logout` in Phase 1).
+- Per-session CSRF token is generated at login and required by every form POST (login, logout, create, edit, delete, bulk actions).
 - `secret_key` must be at least 32 bytes — short keys raise `ValueError` at construction time.
 
 #### 5. Plug in a custom auth backend

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/recipes/admin.md

@@ -1,7 +1,7 @@
 # Painel admin
 
 
-UI de gerenciamento no estilo Django montada sob `/admin`. Operadores entram com uma linha de usuário do banco (sem store de senha de admin separado) e navegam por todo modelo registrado pelo navegador, então a porta do banco pode ficar fechada em redes privadas. A Fase 1 entrega views somente leitura; criar/editar/apagar chegam na 0.14.0 e ações inline + em lote na 0.15.0.
+UI de gerenciamento no estilo Django montada sob `/admin`. Operadores entram com uma linha de usuário do banco (sem store de senha de admin separado) e navegam por todo modelo registrado pelo navegador, então a porta do banco pode ficar fechada em redes privadas. O painel é completo (paridade com o Django admin): list view com busca / filtros por campo / colunas ordenáveis, CRUD completo (criar / editar / excluir), ações em massa, export CSV/JSON, widgets FK-select, dashboard com contagens de linhas + métricas de sistema, MFA TOTP opcional no login, e trilha de auditoria carimbando `created_by` / `updated_by`. Ainda no roadmap: upload de arquivo e edição inline/relacionada.
 
 Requer o extra `[admin]`:
 
@@ -120,11 +120,33 @@ app.include_router(
 `make_admin_router` monta:
 
 - `GET  /admin/login`, `POST /admin/login`, `POST /admin/logout` — fluxo de auth.
-- `GET  /admin/` — dashboard listando todo admin registrado.
-- `GET  /admin/m/{slug}/` — list view com paginação + busca em texto livre (`?q=`) + filtros por campo (`?filter_<field>=value`).
-- `GET  /admin/m/{slug}/{identity}` — detail view somente leitura.
+- `GET/POST /admin/mfa` — desafio TOTP (segundo fator) entre a senha e o acesso, para principais com MFA habilitado.
+- `GET  /admin/` — dashboard: card por modelo com **contagem de linhas** + Browse/New, e um **painel de métricas** (CPU/RAM/disco via `MetricsUtils`). Painel ligado por default, omitido sem o extra `[metrics]`, desligável com `make_admin_router(show_metrics=False)`.
+- `GET  /admin/m/{slug}/` — list view com paginação + busca em texto livre (`?q=`) + filtros por campo (`?filter_<field>=value`) + **ordenação por coluna** clicável (`?sort=<coluna>&dir=asc|desc`).
+- `GET  /admin/m/{slug}/export.csv` / `export.json` — **exporta** o resultado atual (respeitando busca/filtros/ordenação) como CSV ou JSON. Limite de linhas via `make_admin_router(export_max_rows=…)` (default 5000).
+- `POST /admin/m/{slug}/bulk` — **ações em massa** (delete / activate / deactivate) nas linhas selecionadas.
+- `GET/POST /admin/m/{slug}/new` — **criar** registro (quando `can_create`).
+- `GET  /admin/m/{slug}/{identity}` — detail view com botões Edit/Delete.
+- `GET/POST /admin/m/{slug}/{identity}/edit` — **editar** registro (quando `can_edit`).
+- `POST /admin/m/{slug}/{identity}/delete` — **excluir** registro (quando `can_delete`).
 - `GET  /admin/static/{path}` — assets CSS/HTMX embutidos.
 
+!!! info "Escrita (CRUD) + permissões"
+    Create/edit/delete são controlados por flags no `AdminModel`: `can_create` / `can_edit` / `can_delete` (todas `True` por default; uma view desativada responde `404`). Todo POST de escrita carrega o token CSRF da sessão, validado no servidor (`403` em mismatch). Os **widgets de campo** são derivados do tipo da coluna — texto / textarea (strings longas) / number / checkbox / `datetime-local` / date / `select` para enums — com validação de obrigatórios + erros por campo re-renderizados no formulário.
+
+    **Ações em massa**: a list view mostra checkboxes por linha + select-all e uma barra de ação (delete / activate / deactivate) que opera nas linhas marcadas via `POST .../bulk` (CSRF + flags `can_delete`/`can_edit`), apoiada em `BaseRepository.delete_batch` / `bulk_update`.
+
+    **FK-select**: uma coluna FK cujo destino tem `AdminModel` registrado vira um dropdown das linhas relacionadas (igual ao FK select do Django) no formulário, em vez de um input UUID cru. O label da opção vem do primeiro `search_fields` do admin referenciado (fallback: atributo `name`/`title`/`email`, depois o id). Limitado a 1000 linhas; FK para tabela não-gerenciada continua input UUID.
+
+    **MFA no login**: um principal com MFA habilitado (colunas `totp_secret`/`totp_enabled_at` do `MFAMixin`) passa por um desafio TOTP em `/admin/mfa` depois da senha — só um código válido libera o acesso. Habilite passando um usuário com MFA via `UserModelAuthBackend(UserModel, mfa_issuer=...)`; backends customizados sobrescrevem `mfa_enabled`/`verify_mfa`.
+
+    **Audit trail**: create/edit pelo admin carimba `created_by`/`updated_by` (do `AuditMixin`) com o id do admin atuante; o detail mostra um painel **Audit** com timestamps e — quando o modelo tem as colunas de auditoria — o ator (UUID resolvido para nome via o auth backend). Modelos sem `AuditMixin` mostram só os timestamps.
+
+    Ainda **não** incluídos (fases futuras do roadmap): upload de arquivo, inline/related editing.
+
+!!! tip "Responsivo por padrão"
+    Os templates + CSS embutidos são responsivos: em telas estreitas (≤600px) o header empilha, busca/filtros/ações viram full-width, as tabelas ganham scroll horizontal (nunca quebram o layout) e o grid do detail colapsa para uma coluna. Headers de coluna são clicáveis para alternar a ordenação (▲/▼).
+
 #### 4. Defaults de segurança de sessão
 
 `SignedCookieSessionStore` usa `itsdangerous.TimestampSigner` (HMAC-SHA256) para assinar um único cookie:
@@ -133,7 +155,7 @@ app.include_router(
 - `Secure` marcado quando `cookie_secure=True` (padrão; desligue no dev HTTP local).
 - `SameSite=Lax` (`"lax"`/`"strict"`/`"none"` aceitos).
 - Tempo de vida padrão `8h`; cookies expirados ou adulterados são rejeitados silenciosamente.
-- Um token CSRF por sessão é gerado no login e exigido por todo POST de formulário (apenas `logout` na Fase 1).
+- Um token CSRF por sessão é gerado no login e exigido por todo POST de formulário (login, logout, criar, editar, excluir, ações em massa).
 - `secret_key` deve ter ao menos 32 bytes — chaves curtas levantam `ValueError` no momento da construção.
 
 #### 5. Plugue um backend de auth customizado

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/recipes/cli.en.md

@@ -56,9 +56,9 @@ Since v0.25.0 the scaffold generates a `docker-compose.yaml` carrying **only** t
 
 | Extra | Container | Exposed port(s) |
 |-------|-----------|-----------------|
-| (always) | `postgres:16-alpine` | 5432 |
-| `[cache]` | `redis:7-alpine` | 6379 |
-| `[queue]` / `[tasks]` | `rabbitmq:3-management-alpine` | 5672 (AMQP) + 15672 (UI) |
+| (always) | `postgres:18-alpine` | 5432 |
+| `[cache]` | `redis:8-alpine` | 6379 |
+| `[queue]` / `[tasks]` | `rabbitmq:4-management-alpine` | 5672 (AMQP) + 15672 (UI) |
 | `[minio]` | `minio/minio` + bootstrap mc | 9000 (API) + 9001 (Console) |
 | `[email]` | `mailhog/mailhog` | 1025 (SMTP) + 8025 (UI) |
 
@@ -73,6 +73,18 @@ Generates:
 - `postgres`, `redis`, `minio` (+ `minio-bootstrap` creating the `uploads` bucket), `mailhog`
 - `.env.example` with `REDIS_URL`, `MINIO_*`, `EMAIL_HOST=localhost`, `EMAIL_PORT=1025`
 
+!!! info "Credentials come from `.env`, not hardcoded in the compose"
+    As of v0.37.0, no credential is written straight into
+    `docker-compose.yaml`. Each `environment:` block uses the
+    `${VAR:-default}` form, and Docker Compose resolves `VAR` from the
+    `.env` next to the compose file. The `:-default` keeps the stack
+    bootable before you copy `.env.example` to `.env` — but set real
+    secrets in `.env` for any non-throwaway deploy. Variables read by
+    compose: `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`,
+    `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS` /
+    `RABBITMQ_DEFAULT_VHOST`, `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD`
+    — all with their defaults already in `.env.example`.
+
 Boot it all:
 
 ```bash

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/recipes/cli.md

@@ -56,9 +56,9 @@ Desde a v0.25.0 o scaffold gera um `docker-compose.yaml` com **apenas** os servi
 
 | Extra | Container subido | Porta(s) exposta(s) |
 |-------|------------------|---------------------|
-| (sempre) | `postgres:16-alpine` | 5432 |
-| `[cache]` | `redis:7-alpine` | 6379 |
-| `[queue]` / `[tasks]` | `rabbitmq:3-management-alpine` | 5672 (AMQP) + 15672 (UI) |
+| (sempre) | `postgres:18-alpine` | 5432 |
+| `[cache]` | `redis:8-alpine` | 6379 |
+| `[queue]` / `[tasks]` | `rabbitmq:4-management-alpine` | 5672 (AMQP) + 15672 (UI) |
 | `[minio]` | `minio/minio` + bootstrap mc | 9000 (API) + 9001 (Console) |
 | `[email]` | `mailhog/mailhog` | 1025 (SMTP) + 8025 (UI) |
 
@@ -73,6 +73,18 @@ Gera:
 - `postgres`, `redis`, `minio` (+ `minio-bootstrap` que cria o bucket `uploads`), `mailhog`
 - `.env.example` com `REDIS_URL`, `MINIO_*`, `EMAIL_HOST=localhost`, `EMAIL_PORT=1025`
 
+!!! info "Credenciais vêm do `.env`, não estão hardcoded no compose"
+    A partir da v0.37.0, nenhuma credencial é gravada direto no
+    `docker-compose.yaml`. Cada bloco `environment:` usa a forma
+    `${VAR:-default}`, e o Docker Compose resolve `VAR` a partir do
+    `.env` ao lado do compose. O `:-default` mantém o stack subindo
+    antes de você copiar `.env.example` para `.env` — mas defina
+    segredos reais no `.env` para qualquer deploy não-descartável.
+    Variáveis lidas pelo compose: `POSTGRES_USER` / `POSTGRES_PASSWORD`
+    / `POSTGRES_DB`, `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS`
+    / `RABBITMQ_DEFAULT_VHOST`, `MINIO_ROOT_USER` /
+    `MINIO_ROOT_PASSWORD` — todas com seus padrões já no `.env.example`.
+
 Subir tudo:
 
 ```bash

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/recipes/uploads.en.md

@@ -151,4 +151,4 @@ url = await storage.presigned_url("logo.png", expires=timedelta(hours=1))
 
 ## When to use presigned PUT directly
 
-For files > 50 MB, skip the in-memory buffer — have the client `PUT` straight to MinIO via a presigned URL. See [Storage MinIO/S3](storage.md#presigned-url--direct-browser-upload).
+For files > 50 MB, skip the in-memory buffer — have the client `PUT` straight to MinIO via a presigned URL. See [Storage MinIO/S3](storage.md#presigned-url-direct-browser-upload).

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.37.0}/docs/reference.md

@@ -26,9 +26,14 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 
 ::: tempest_fastapi_sdk.db.model.BaseModel
 ::: tempest_fastapi_sdk.db.user_model.BaseUserModel
+::: tempest_fastapi_sdk.db.user_token_model.BaseUserTokenModel
+::: tempest_fastapi_sdk.db.user_token_model.make_user_token_model
+::: tempest_fastapi_sdk.db.user_recovery_code_model.BaseUserRecoveryCodeModel
+::: tempest_fastapi_sdk.db.user_recovery_code_model.make_user_recovery_code_model
 ::: tempest_fastapi_sdk.db.repository.BaseRepository
 ::: tempest_fastapi_sdk.db.mixins.SoftDeleteMixin
 ::: tempest_fastapi_sdk.db.mixins.AuditMixin
+::: tempest_fastapi_sdk.db.mixins.MFAMixin
 ::: tempest_fastapi_sdk.db.connection.AsyncDatabaseManager
 ::: tempest_fastapi_sdk.db.migrations.AlembicHelper
 
@@ -120,6 +125,10 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ::: tempest_fastapi_sdk.auth.schemas.PasswordResetConfirmSchema
 ::: tempest_fastapi_sdk.auth.schemas.ActivationToken
 ::: tempest_fastapi_sdk.auth.schemas.PasswordResetToken
+::: tempest_fastapi_sdk.auth.schemas.MFAEnrollResponseSchema
+::: tempest_fastapi_sdk.auth.schemas.MFAConfirmSchema
+::: tempest_fastapi_sdk.auth.schemas.MFAVerifySchema
+::: tempest_fastapi_sdk.auth.schemas.MFADisableSchema
 
 ### `tempest_fastapi_sdk.sessions`
 
@@ -211,6 +220,7 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 
 ::: tempest_fastapi_sdk.utils.password.PasswordUtils
 ::: tempest_fastapi_sdk.utils.jwt.JWTUtils
+::: tempest_fastapi_sdk.utils.totp.TOTPHelper
 ::: tempest_fastapi_sdk.utils.email.EmailUtils
 ::: tempest_fastapi_sdk.utils.upload.UploadUtils
 ::: tempest_fastapi_sdk.utils.metrics.MetricsUtils