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

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

@@ -5,6 +5,91 @@ 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.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.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.35.0
+Version: 0.36.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
@@ -174,7 +174,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.35.0",
+    "tempest-fastapi-sdk>=0.36.0",
 ]
 ```
 

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

@@ -89,7 +89,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.35.0",
+    "tempest-fastapi-sdk>=0.36.0",
 ]
 ```
 

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

@@ -29,6 +29,7 @@ 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 |
 | `[all]` | everything above | every helper |
 
 === "Subset (recommended)"

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

@@ -29,6 +29,7 @@ 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 |
 | `[all]` | tudo acima | todos os helpers |
 
 === "Subconjunto (recomendado)"

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

@@ -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:

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

@@ -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:

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.36.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

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.36.0}/docs/roadmap.en.md

@@ -32,7 +32,7 @@ What the SDK **doesn't ship yet** + what already landed. Sorted by impact, not i
 | 2FA / TOTP (`pyotp` wrapper + recovery codes) | ✅ v0.35.0 | `TOTPHelper` + `UserAuthService.mfa_*` + `BaseUserRecoveryCodeModel` |
 | `tempest db` + `tempest user` CLI | ✅ v0.30.0 | `tempest_fastapi_sdk.cli.db` / `cli.user` |
 | `BaseRepository.bulk_update` (filters + values) | ✅ pre-existing | `BaseRepository.bulk_update` |
-| **Multi-tenant scope** — `TenantScopedRepository(tenant_id)` auto-injecting `WHERE tenant_id = …` on every repository query | ❌ planned v0.36.0 | — |
+| **Multi-tenant scope** — `TenantScopedRepository(tenant_id)` auto-injecting `WHERE tenant_id = …` on every repository query | ❌ planned v0.37.0 | — |
 
 ## Tier B — when the service grows
 
@@ -50,6 +50,21 @@ What the SDK **doesn't ship yet** + what already landed. Sorted by impact, not i
 | `tempest db seed` — load JSON/Python fixtures | ❌ pending |
 | CLI: `tempest secrets rotate` | ❌ pending |
 
+## Admin panel — evolution
+
+The admin panel already exists (`AdminSite` / `AdminModel` / `make_admin_router`, Jinja + HTMX, CSRF token). The items below take it from "functional CRUD" to "production admin", reusing primitives the SDK already ships (`AuditMixin`, `MetricsUtils`, `TOTPHelper`, `UploadUtils`).
+
+| Feature | Why it matters | Reuses |
+|---------|----------------|--------|
+| **Per-column filter / search / sort** on the list view | Large lists are unusable without it — the first thing every operator asks for. | `BaseRepository` (filters + pagination) |
+| **Bulk actions** (mass delete / activate) | Row-by-row actions don't scale; select N rows + one action is the standard admin flow. | `BaseRepository.bulk_update` / soft-delete |
+| **Field widgets** (FK select, date picker, file upload) | The form is generic today; FK as `<select>`, dates with a picker, and upload via `UploadUtils` remove manual typing and error. | `UploadUtils` + storage backends |
+| **Inline / related editing** | Edit children (1-N) on the parent's screen — the Django-admin pattern that's missing. | `BaseRepository` + relationships |
+| **CSV / JSON export** | Operator exports the filtered result without opening the database. | list view + filters |
+| **Audit log visible in the admin** | Who changed what and when, straight in the UI. | `AuditMixin` (`created_by` / `updated_by`) |
+| **Metrics dashboard** | A landing screen with CPU/RAM/counters instead of an empty page. | `MetricsUtils` |
+| **MFA on admin login** | Second factor on the most sensitive access in the system; a natural fit now that TOTP exists. | `TOTPHelper` + `MFAMixin` + recovery codes |
+
 ## Everything shipped so far
 
 ### ✅ v0.23.0 — MinIO/S3 storage

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.36.0}/docs/roadmap.md

@@ -32,7 +32,7 @@ Esta página lista o que o SDK **ainda não oferece** + o que já foi entregue.
 | 2FA / TOTP (`pyotp` wrapper + recovery codes) | ✅ v0.35.0 | `TOTPHelper` + `UserAuthService.mfa_*` + `BaseUserRecoveryCodeModel` |
 | `tempest db` + `tempest user` CLI | ✅ v0.30.0 | `tempest_fastapi_sdk.cli.db` / `cli.user` |
 | `BaseRepository.bulk_update` (filters + values) | ✅ pré-existente | `BaseRepository.bulk_update` |
-| **Escopo multi-tenant** — `TenantScopedRepository(tenant_id)` auto-injetando `WHERE tenant_id = …` em toda query do repository | ❌ planejado v0.36.0 | — |
+| **Escopo multi-tenant** — `TenantScopedRepository(tenant_id)` auto-injetando `WHERE tenant_id = …` em toda query do repository | ❌ planejado v0.37.0 | — |
 
 ## Tier B — quando o serviço crescer
 
@@ -50,6 +50,21 @@ Esta página lista o que o SDK **ainda não oferece** + o que já foi entregue.
 | `tempest db seed` — carregar fixtures JSON/Python | ❌ pendente |
 | CLI: `tempest secrets rotate` | ❌ pendente |
 
+## Painel admin — evolução
+
+O painel admin já existe (`AdminSite` / `AdminModel` / `make_admin_router`, Jinja + HTMX, CSRF token). Os itens abaixo elevam ele de "CRUD funcional" para "admin de produção", reaproveitando primitivos que o SDK já tem (`AuditMixin`, `MetricsUtils`, `TOTPHelper`, `UploadUtils`).
+
+| Feature | Por que importa | Reaproveita |
+|---------|-----------------|-------------|
+| **Filtros / busca / ordenação por coluna** na listagem | Listas grandes ficam inutilizáveis sem isso; é o primeiro pedido de todo operador. | `BaseRepository` (filtros + paginação) |
+| **Bulk actions** (deletar / ativar em massa) | Ações linha-a-linha não escalam; selecionar N linhas + uma ação é o fluxo padrão de admin. | `BaseRepository.bulk_update` / soft-delete |
+| **Widgets de campo** (FK select, date picker, file upload) | Hoje o form é genérico; FK como `<select>`, data com picker e upload via `UploadUtils` removem digitação manual e erro. | `UploadUtils` + storage backends |
+| **Inline / related editing** | Editar filhos (1-N) na mesma tela do pai — padrão Django admin que falta. | `BaseRepository` + relationships |
+| **Export CSV / JSON** | Operador exporta o resultado filtrado sem abrir o banco. | listagem + filtros |
+| **Audit log visível no admin** | Quem mudou o quê e quando, direto na UI. | `AuditMixin` (`created_by` / `updated_by`) |
+| **Dashboard com métricas** | Tela inicial com CPU/RAM/contadores em vez de página vazia. | `MetricsUtils` |
+| **MFA no login do admin** | Segundo fator no acesso mais sensível do sistema; encaixe natural agora que o TOTP existe. | `TOTPHelper` + `MFAMixin` + recovery codes |
+
 ## Tudo que já entregamos
 
 ### ✅ v0.23.0 — Storage MinIO/S3

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.36.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.35.0"
+version = "0.36.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.35.0 → tempest_fastapi_sdk-0.36.0}/tempest_fastapi_sdk/__init__.py

@@ -242,7 +242,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.35.0"
+__version__: str = "0.36.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.36.0}/tempest_fastapi_sdk/admin/auth.py

@@ -123,6 +123,37 @@ class AdminAuthBackend(ABC):
         email = getattr(principal, "email", None)
         return str(email) if email else repr(principal)
 
+    def mfa_enabled(self, principal: Any) -> bool:
+        """Whether ``principal`` must pass a TOTP challenge after login.
+
+        Defaults to ``False`` so non-user backends (LDAP, OAuth) skip
+        the second factor unless they opt in. Override to gate the
+        login behind MFA.
+
+        Args:
+            principal (Any): The authenticated principal.
+
+        Returns:
+            bool: ``True`` to require the TOTP step.
+        """
+        return False
+
+    def verify_mfa(self, principal: Any, code: str) -> bool:
+        """Verify a submitted TOTP ``code`` for ``principal``.
+
+        Only called when :meth:`mfa_enabled` returned ``True``. The
+        default rejects everything; backends that enable MFA must
+        override it.
+
+        Args:
+            principal (Any): The authenticated principal.
+            code (str): The 6-digit code from the authenticator app.
+
+        Returns:
+            bool: ``True`` when the code is valid.
+        """
+        return False
+
 
 class UserModelAuthBackend(AdminAuthBackend):
     """Default backend backed by :class:`BaseUserModel`.
@@ -138,11 +169,20 @@ class UserModelAuthBackend(AdminAuthBackend):
             Must be a subclass of :class:`BaseUserModel`.
     """
 
-    def __init__(self, user_model: type[BaseUserModel]) -> None:
+    def __init__(
+        self,
+        user_model: type[BaseUserModel],
+        *,
+        mfa_issuer: str = "Admin",
+        mfa_window: int = 1,
+    ) -> None:
         """Initialize the backend.
 
         Args:
             user_model (type[BaseUserModel]): The user model to query.
+            mfa_issuer (str): Issuer label used when verifying TOTP
+                codes (matches what the authenticator app stored).
+            mfa_window (int): TOTP clock-drift tolerance in 30s steps.
 
         Raises:
             TypeError: When ``user_model`` is not a subclass of
@@ -155,6 +195,8 @@ class UserModelAuthBackend(AdminAuthBackend):
                 "user_model must be a subclass of BaseUserModel",
             )
         self.user_model: type[BaseUserModel] = user_model
+        self.mfa_issuer: str = mfa_issuer
+        self.mfa_window: int = mfa_window
 
     async def authenticate(
         self,
@@ -235,6 +277,48 @@ class UserModelAuthBackend(AdminAuthBackend):
         """
         return str(principal.id)
 
+    def mfa_enabled(self, principal: Any) -> bool:
+        """Whether the user has completed MFA enrollment.
+
+        True when the user carries a populated ``totp_secret`` and a
+        non-null ``totp_enabled_at`` (from
+        :class:`tempest_fastapi_sdk.MFAMixin`). Users without the mixin
+        simply never enable MFA.
+
+        Args:
+            principal (Any): A :class:`BaseUserModel` instance.
+
+        Returns:
+            bool: ``True`` to require the TOTP step.
+        """
+        return bool(
+            getattr(principal, "totp_secret", None)
+            and getattr(principal, "totp_enabled_at", None)
+        )
+
+    def verify_mfa(self, principal: Any, code: str) -> bool:
+        """Verify ``code`` against the user's persisted TOTP secret.
+
+        Args:
+            principal (Any): A :class:`BaseUserModel` instance.
+            code (str): The submitted authenticator code.
+
+        Returns:
+            bool: ``True`` when the code is valid.
+
+        Raises:
+            ImportError: When the ``[mfa]`` extra (``pyotp``) is not
+                installed but a user has MFA enabled.
+        """
+        from tempest_fastapi_sdk.utils.totp import TOTPHelper
+
+        secret = getattr(principal, "totp_secret", None)
+        if not secret:
+            return False
+        return TOTPHelper(issuer=self.mfa_issuer).verify(
+            secret, code, window=self.mfa_window
+        )
+
 
 __all__: list[str] = [
     "AdminAuthBackend",

{tempest_fastapi_sdk-0.35.0 → tempest_fastapi_sdk-0.36.0}/tempest_fastapi_sdk/admin/config.py

@@ -72,6 +72,12 @@ class AdminModel(Generic[ModelT]):
             model name humanized.
         verbose_name_plural (str | None): Plural display name; defaults to
             ``verbose_name + "s"``.
+        can_create (bool): Whether the admin exposes the create form +
+            POST endpoint. Default ``True``.
+        can_edit (bool): Whether the admin exposes the edit form + POST
+            endpoint. Default ``True``.
+        can_delete (bool): Whether the admin exposes the delete action.
+            Default ``True``.
 
     Raises:
         TypeError: When ``model`` is not a subclass of :class:`BaseModel`,
@@ -92,6 +98,9 @@ class AdminModel(Generic[ModelT]):
         repository_class: type[BaseRepository[Any]] | None = None,
         verbose_name: str | None = None,
         verbose_name_plural: str | None = None,
+        can_create: bool = True,
+        can_edit: bool = True,
+        can_delete: bool = True,
     ) -> None:
         """Build and validate the configuration. See class docstring."""
         if not isinstance(model, type) or not issubclass(model, BaseModel):
@@ -112,6 +121,9 @@ class AdminModel(Generic[ModelT]):
         self.repository_class: type[BaseRepository[Any]] | None = repository_class
         self.verbose_name: str | None = verbose_name
         self.verbose_name_plural: str | None = verbose_name_plural
+        self.can_create: bool = can_create
+        self.can_edit: bool = can_edit
+        self.can_delete: bool = can_delete
 
     def get_verbose_name(self) -> str:
         """Return the configured (or auto-derived) singular display name.
@@ -165,6 +177,25 @@ class AdminModel(Generic[ModelT]):
             return list(self.list_display)
         return [name for name in self.column_names() if name not in {"hashed_password"}]
 
+    def editable_field_names(self) -> list[str]:
+        """Return the columns a create/edit form should expose.
+
+        Excludes the primary key, the audit timestamps
+        (``created_at`` / ``updated_at``), the password hash, and any
+        column listed in ``readonly_fields`` — none of which a user
+        edits directly through the generic admin form.
+
+        Returns:
+            list[str]: Editable column keys in declaration order.
+        """
+        skip = set(self.readonly_fields) | {
+            "id",
+            "created_at",
+            "updated_at",
+            "hashed_password",
+        }
+        return [name for name in self.column_names() if name not in skip]
+
     def build_repository(self, session: AsyncSession) -> BaseRepository[ModelT]:
         """Instantiate the repository for ``session``.