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

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

@@ -5,6 +5,161 @@ 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
+
+- **MFA / TOTP (RFC 6238)** — the bundled auth flow now supports
+  two-factor authentication with Authenticator apps. New `[mfa]`
+  extra (`pyotp>=2.9.0`). Public surface:
+    - `TOTPHelper(issuer=...)` — stateless TOTP issuer/verifier
+      (`generate_secret`, `provisioning_uri`, `verify` with a
+      configurable clock-drift window). Lazy-imports `pyotp`, so
+      `import tempest_fastapi_sdk` still works without the extra.
+    - `BaseUserRecoveryCodeModel` + `make_user_recovery_code_model`
+      — single-use recovery-code table (stores only the SHA-256
+      hash of each code, mirroring `BaseUserTokenModel`).
+    - `MFAMixin` — opt-in SQLAlchemy mixin adding `totp_secret` +
+      `totp_enabled_at` columns (plus an `is_mfa_active` property).
+      Mix it into the concrete user model
+      (`class UserModel(MFAMixin, BaseUserModel)`) only when MFA is
+      adopted, so projects that never enable it carry no dead
+      columns. `totp_enabled_at IS NULL` means MFA is
+      staged-but-not-active, so login stays single-step until the
+      user confirms.
+    - `UserAuthService` MFA methods: `is_mfa_enrolled`,
+      `issue_mfa_token`, `mfa_enroll`, `mfa_confirm`, `mfa_verify`,
+      `mfa_disable`.
+    - `make_auth_router(..., recovery_code_model=...)` mounts four
+      endpoints behind the `AUTH_MFA_ENABLED` kill-switch:
+      `POST /auth/mfa/enroll`, `/auth/mfa/confirm`,
+      `/auth/mfa/disable`, `/auth/mfa/verify`. `POST /auth/login`
+      now returns `mfa_required=True` + a short-lived `mfa_token`
+      (instead of the JWT pair) for enrolled users; step 2 swaps
+      `mfa_token` + code for the real tokens.
+    - New schemas: `MFAEnrollResponseSchema`, `MFAConfirmSchema`,
+      `MFADisableSchema`, `MFAVerifySchema`. `LoginResponseSchema`
+      gains `mfa_required` + `mfa_token` (and `access_token` /
+      `refresh_token` are now nullable for the MFA-pending case).
+    - New `AuthSettings`: `AUTH_MFA_ENABLED`, `AUTH_MFA_ISSUER`,
+      `AUTH_MFA_RECOVERY_CODES_COUNT`, `AUTH_MFA_TOKEN_TTL_SECONDS`,
+      `AUTH_MFA_VERIFY_WINDOW`.
+- **Optional password complexity** — new
+  `AUTH_PASSWORD_REQUIRE_COMPLEXITY` flag (default `False`). When off,
+  any password meeting `AUTH_PASSWORD_MIN_LENGTH` is accepted; when on,
+  signup + reset additionally require at least one lowercase letter,
+  one uppercase letter, one digit, and one special (non-alphanumeric)
+  character, and the effective length floor is raised to at least 8
+  (a configured `AUTH_PASSWORD_MIN_LENGTH` below 8 is ignored while
+  complexity is on). Enforced server-side on both `service.signup` and
+  `service.confirm_password_reset`.
+
+### Fixed
+
+- **Password minimum length is now honored end-to-end.**
+  `SignupSchema.password` and `PasswordResetConfirmSchema.new_password`
+  hardcoded `min_length=12`, which overrode `AUTH_PASSWORD_MIN_LENGTH`
+  on the router path — a project lowering the floor still got a 422
+  from Pydantic, and raising it above 12 was enforced only by the
+  service. The schemas now reject only empty strings;
+  `AUTH_PASSWORD_MIN_LENGTH` is the single source of truth (now `ge=1`,
+  fully configurable down to 4 or any value, default 12), applied
+  server-side.
+
+### Notes
+
+- Enabling MFA requires a migration: mix `MFAMixin` into the concrete
+  user model (`class UserModel(MFAMixin, BaseUserModel)`) to add the
+  `totp_secret` / `totp_enabled_at` columns, and create the
+  recovery-code table. `AUTH_MFA_ENABLED=True` without passing
+  `recovery_code_model` to `make_auth_router` raises at
+  router-build time.
+
 ## [0.34.0] — 2026-06-04
 
 ### Added

{tempest_fastapi_sdk-0.34.0 → tempest_fastapi_sdk-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.34.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
@@ -44,6 +44,7 @@ Requires-Dist: nvidia-ml-py>=12.560.30; extra == 'all'
 Requires-Dist: prometheus-client>=0.20.0; extra == 'all'
 Requires-Dist: psutil>=6.0.0; extra == 'all'
 Requires-Dist: pyjwt>=2.12.1; extra == 'all'
+Requires-Dist: pyotp>=2.9.0; extra == 'all'
 Requires-Dist: python-multipart>=0.0.12; extra == 'all'
 Requires-Dist: pywebpush>=2.0.0; extra == 'all'
 Requires-Dist: redis>=5.0.0; extra == 'all'
@@ -63,6 +64,8 @@ Requires-Dist: httpx>=0.28.0; extra == 'http'
 Provides-Extra: metrics
 Requires-Dist: nvidia-ml-py>=12.560.30; extra == 'metrics'
 Requires-Dist: psutil>=6.0.0; extra == 'metrics'
+Provides-Extra: mfa
+Requires-Dist: pyotp>=2.9.0; extra == 'mfa'
 Provides-Extra: minio
 Requires-Dist: minio>=7.2.0; extra == 'minio'
 Provides-Extra: prometheus
@@ -171,7 +174,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.32.0",
+    "tempest-fastapi-sdk>=0.36.0",
 ]
 ```
 
@@ -195,6 +198,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[minio]` | `minio` | `AsyncMinIOClient`, `ObjectStat`, `MinIOSettings` |
 | `[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 |
 | `[all]` | everything above | every helper |
 
 ```bash
@@ -211,11 +215,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck` |
-| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken` — signup/activate/login/reset out of the box |
+| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`) — signup/activate/login/reset + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum` |
@@ -228,7 +232,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
-| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, BR regex helpers (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`) |
+| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, BR regex helpers (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).

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

@@ -89,7 +89,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.32.0",
+    "tempest-fastapi-sdk>=0.36.0",
 ]
 ```
 
@@ -113,6 +113,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[minio]` | `minio` | `AsyncMinIOClient`, `ObjectStat`, `MinIOSettings` |
 | `[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 |
 | `[all]` | everything above | every helper |
 
 ```bash
@@ -129,11 +130,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck` |
-| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken` — signup/activate/login/reset out of the box |
+| `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`) — signup/activate/login/reset + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum` |
@@ -146,7 +147,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
-| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, BR regex helpers (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`) |
+| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, BR regex helpers (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).

{tempest_fastapi_sdk-0.34.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.34.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.34.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.34.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.34.0 → tempest_fastapi_sdk-0.36.0}/docs/recipes/auth-flow.en.md

@@ -167,7 +167,8 @@ Variables (with production-safe defaults):
 # .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
+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
 
 # .env — token TTL
 AUTH_ACTIVATION_TTL_SECONDS=604800      # 7 days

{tempest_fastapi_sdk-0.34.0 → tempest_fastapi_sdk-0.36.0}/docs/recipes/auth-flow.md

@@ -167,7 +167,8 @@ Variáveis (com defaults seguros pra produção):
 # .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
+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
 
 # .env — TTL dos tokens
 AUTH_ACTIVATION_TTL_SECONDS=604800      # 7 dias