tempest-fastapi-sdk 0.166.1__tar.gz → 0.167.1__tar.gz

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/CHANGELOG.md

@@ -5,6 +5,89 @@ 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.167.1] — 2026-07-26
+
+### Fixed
+
+- **`BaseController` now accepts services typed over a concrete update
+  schema.** `ServiceT`'s bound was written `BaseService[Any, Any]`, which is not
+  a partial application: PEP 696 fills the omitted `UpdateT` with its
+  `BaseSchema` default, and since that parameter is invariant the bound admitted
+  only services whose update schema was exactly `BaseSchema`. Every service
+  written the documented way — `BaseService[Repo, Resp, MyUpdateSchema]` — was
+  rejected by the type checker with `Type parameter "UpdateT@BaseService" is
+  invariant, but "MyUpdateSchema" is not the same as "BaseSchema"`, forcing a
+  `# type: ignore[type-var]` on the controller declaration. The bound is now
+  `BaseService[Any, Any, Any]`, which leaves the invariant parameter open while
+  keeping the `BaseSchema` constraint. Type-check only — runtime behavior is
+  unchanged, and the `# type: ignore[type-var]` workarounds can be dropped.
+- **The suite can now see this class of bug.** `mypy` runs over the package, not
+  over `tests/`, so `tests/controllers/test_base.py` already declared exactly
+  this service/controller pair and stayed green. New
+  `tests/controllers/test_generic_bounds.py` inspects `ServiceT.__bound__`
+  directly and runs `mypy --strict` over a downstream-shaped snippet, asserting
+  no `[type-var]` diagnostic.
+
+### Documentation
+
+- `docs/architecture.md` / `docs/architecture.en.md` — the controllers & services
+  section now shows the 3rd generic parameter on both layers and notes that the
+  pair requires 0.167.1+.
+
+## [0.167.0] — 2026-07-26
+
+Permission guards: a decorator that runs plain `(user) -> user | None`
+functions before a function body, plus the two-layer misuse check the user
+asked for — fail-fast at import time, static gate in CI.
+
+### Added
+
+- **`@requires(*guards, user_param=None)`** (`tempest_fastapi_sdk.authz`,
+  re-exported at the package root). Runs each guard on the user before the
+  decorated body, left to right, on a route handler, a controller or a service
+  method, sync or `async`. A guard receives the user, denies by raising an
+  `AppException` subclass (so the status, the error `code` and the
+  `{detail, code, details}` envelope come from `register_exception_handlers`),
+  and returns the user or `None`; a non-`None` return replaces the user the next
+  guard and the body see, which is how `require_authenticated` /
+  `require_active` / `require_admin` narrow `UserT | None` to `UserT`.
+  The user parameter is resolved from the annotations — the single parameter
+  typed as a `BaseModel` / `BaseUserModel` subclass — with `user_param=` to
+  name it explicitly or disambiguate two user models. The wrapper keeps the
+  decorated signature (with annotations already evaluated, so FastAPI resolves
+  them against the right module), leaving dependency injection and the OpenAPI
+  schema untouched.
+- **`TempestPermissionError`** — raised at decoration time (import time) for
+  `@requires()` with no guard, a non-callable guard, a guard that does not take
+  exactly one fillable parameter, an `async` guard under a synchronous function,
+  or a decorated function whose user parameter cannot be resolved. The
+  application refuses to start instead of running a check that never fires.
+- **`GuardContractWarning`** — warned at call time when a guard raises outside
+  the `AppException` hierarchy (the API layer would answer HTTP 500 with no
+  error code) or returns a non-user value such as `False` (a predicate-style
+  check whose denial cannot be honored). The original exception still
+  propagates; the warning names the guard.
+- **`declared_guards(fn)` / `guarded_user_param(fn)`** — read a function's
+  guards and its user parameter without calling it, for a router audit or a
+  test asserting every write route carries a guard.
+- **`tempest permissions [--check] [--strict] [--path]`** — static contract
+  check over the project source (`ast`, without importing the application), for
+  what runtime validation cannot see: a guard whose `raise` no test exercises, a
+  guard never wired. Errors: `no-guards`, `user-param-missing`,
+  `user-param-ambiguous`, `guard-arity`, `guard-async-in-sync`,
+  `guard-returns-bool`, `guard-foreign-exception`. Warnings:
+  `guard-never-denies`, `guard-missing-annotation`, `guard-return-type`,
+  `guard-unresolved`. `--check` exits non-zero on errors, `--strict` on warnings
+  too. Guards resolve by name; an ambiguous or out-of-scope name is reported as
+  `guard-unresolved` rather than checked against the wrong definition.
+
+### Changed
+
+- **`tempest openapi-errors` now follows `@requires` guards.** A guard denies by
+  raising, so its exceptions are as reachable from the route as those of any
+  function the body calls; they now show up as `undocumented` until the route
+  declares them, and `--fix` writes them like any other.
+
 ## [0.166.1] — 2026-07-25
 
 Post-release validation of `--fix` against the published wheel, in a project

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/CLAUDE.md

@@ -75,6 +75,24 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   `refresh_token_model=` on `UserAuthService`) with rotation,
   family-wide reuse detection and `POST /auth/logout`
   (`LogoutSchema`).
+- **Permission guards (v0.167.0)** — `@requires(*guards, user_param=None)`
+  (`tempest_fastapi_sdk.authz`, re-exported at the root) runs plain
+  `(user) -> user | None` guards before a function body, at any layer, sync or
+  async; guards deny by raising an `AppException`, and a non-`None` return
+  replaces the user the body sees (how `require_active` narrows `UserT | None`).
+  The user param resolves from the annotations (`BaseModel`/`BaseUserModel`
+  subclass), `user_param=` disambiguates. Misuse caught in three places:
+  `TempestPermissionError` at import (no guard, wrong arity, async guard on a
+  sync fn, unresolvable user param), `GuardContractWarning` at call time
+  (foreign exception, `return False`), and
+  `tempest permissions [--check|--strict|--path]` statically (`ast`) — errors
+  `no-guards`/`user-param-missing`/`user-param-ambiguous`/`guard-arity`/
+  `guard-async-in-sync`/`guard-returns-bool`/`guard-foreign-exception`,
+  warnings `guard-never-denies`/`guard-missing-annotation`/`guard-return-type`/
+  `guard-unresolved` (ambiguous or out-of-scope guard reported, never guessed).
+  `openapi-errors` follows the guards, so their exceptions land in
+  `error_responses(...)`. `declared_guards`/`guarded_user_param` introspect a
+  route. Recipe: `docs/recipes/permission-guards.md`.
 - **DB** — `AsyncDatabaseManager`, `BaseRepository[T]` with
   bulk ops (`bulk_create_values`, `bulk_upsert`, `bulk_update`,
   `add_all`, etc.), `AlembicHelper`, `BaseModel`, audit /
@@ -377,7 +395,7 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   `tempest db init/revision/upgrade/downgrade/current/history/seed`,
   `tempest user create [--admin] / list`, `tempest secrets rotate`,
   plus quality gates (`lint`, `fix`, `format`, `fmt-check`, `type`,
-  `test`, `check`), `openapi-errors`, `openapi-client`.
+  `test`, `check`), `openapi-errors`, `openapi-client`, `permissions`.
 
 The whole Tier S / Tier A / Tier B backlog that used to live here is
 **shipped**, and so is the five-item next-version plan that followed it

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.166.1
+Version: 0.167.1
 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
@@ -237,7 +237,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.161.0",
+    "tempest-fastapi-sdk>=0.167.0",
 ]
 ```
 
@@ -302,7 +302,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, OpenAPI error docs (`error_responses`, `raises`, `TempestAPIRouter`, `RaisesSpec`, `declared_raises`), `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `BusinessMetrics`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, outbound `WebhookSender` (+ `WebhookDelivery`), OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `make_spa_router` (serve a compiled React/Vite SPA with a client-side fallback), `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, email change/verify/recovery (`EmailChangeRequestSchema` / `EmailChangeConfirmSchema` / `EmailRecoveryRequestSchema` / `EmailChangeToken` / `EmailVerificationToken`, old-email security notice, opt-in `AUTH_EMAIL_RECOVERY_ENABLED`), MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + email change/recovery + TOTP 2FA out of the box |
-| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry` |
+| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry`, `requires` (guard decorator `(user) -> user | None`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param`, `TempestPermissionError`, `GuardContractWarning` |
 | `tempest_fastapi_sdk.checks` | System checks (Django-style config validation): `check` (register decorator), `run_checks` / `run_system_checks` (raises `SystemCheckError` on ERROR+), `CheckMessage` / `CheckLevel` + `debug`/`info`/`warning`/`error`/`critical`, `CheckRegistry` / `default_registry`; built-in settings checks + the `tempest check-config` CLI (auto-detects settings, `--tag` / `--fail-level`) |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
@@ -4147,6 +4147,39 @@ tempest openapi-errors --fix             # write them (needs a clean git tree)
 
 ---
 
+### Permission guards
+
+`@requires` runs plain `(user) -> user | None` guards before a function body — on a route, a controller or a service, sync or `async`. A guard denies by raising an `AppException`, so the HTTP status, the error `code` and the `{detail, code, details}` envelope come from the SDK handlers.
+
+```python
+from fastapi import Depends
+from tempest_fastapi_sdk import error_responses, requires
+from tempest_fastapi_sdk.auth import require_active
+
+
+@router.delete("/orders/{order_id}", responses=error_responses(NotOrderOwnerException))
+@requires(require_active, order_owner)
+async def delete_order(
+    order_id: UUID,
+    user: UserModel = Depends(get_current_user),
+) -> None:
+    """The body runs only for an active user who owns the order."""
+    await controller.delete(order_id)
+```
+
+The user parameter is found by annotation (`user_param=` breaks a tie), and a guard's non-`None` return replaces the user the body sees — which is how `require_active` narrows `UserT | None` to `UserT`.
+
+Misuse is caught in three places: `TempestPermissionError` at import time (no guard, wrong arity, `async` guard on a sync function, no user parameter), `GuardContractWarning` at call time (a guard raising outside the `AppException` hierarchy, or returning `False` instead of denying), and `tempest permissions --check` in CI, which reads the same contract statically.
+
+```bash
+tempest permissions --check            # exit 1 on any error
+tempest permissions --check --strict   # fail on warnings too
+```
+
+`tempest openapi-errors` reads the `@requires` guards too, so a guard's exception shows up as `undocumented` on the route until it is declared. Full walkthrough: [Permission guards](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/en/recipes/permission-guards/).
+
+---
+
 ## Conventions
 
 - **Layered architecture**: routers → controllers → services → repositories. Never skip layers.

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/README.md

@@ -91,7 +91,7 @@ Via `pyproject.toml`:
 
 ```toml
 dependencies = [
-    "tempest-fastapi-sdk>=0.161.0",
+    "tempest-fastapi-sdk>=0.167.0",
 ]
 ```
 
@@ -156,7 +156,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, OpenAPI error docs (`error_responses`, `raises`, `TempestAPIRouter`, `RaisesSpec`, `declared_raises`), `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `BusinessMetrics`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, outbound `WebhookSender` (+ `WebhookDelivery`), OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `make_spa_router` (serve a compiled React/Vite SPA with a client-side fallback), `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, email change/verify/recovery (`EmailChangeRequestSchema` / `EmailChangeConfirmSchema` / `EmailRecoveryRequestSchema` / `EmailChangeToken` / `EmailVerificationToken`, old-email security notice, opt-in `AUTH_EMAIL_RECOVERY_ENABLED`), MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + email change/recovery + TOTP 2FA out of the box |
-| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry` |
+| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry`, `requires` (guard decorator `(user) -> user | None`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param`, `TempestPermissionError`, `GuardContractWarning` |
 | `tempest_fastapi_sdk.checks` | System checks (Django-style config validation): `check` (register decorator), `run_checks` / `run_system_checks` (raises `SystemCheckError` on ERROR+), `CheckMessage` / `CheckLevel` + `debug`/`info`/`warning`/`error`/`critical`, `CheckRegistry` / `default_registry`; built-in settings checks + the `tempest check-config` CLI (auto-detects settings, `--tag` / `--fail-level`) |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
@@ -4001,6 +4001,39 @@ tempest openapi-errors --fix             # write them (needs a clean git tree)
 
 ---
 
+### Permission guards
+
+`@requires` runs plain `(user) -> user | None` guards before a function body — on a route, a controller or a service, sync or `async`. A guard denies by raising an `AppException`, so the HTTP status, the error `code` and the `{detail, code, details}` envelope come from the SDK handlers.
+
+```python
+from fastapi import Depends
+from tempest_fastapi_sdk import error_responses, requires
+from tempest_fastapi_sdk.auth import require_active
+
+
+@router.delete("/orders/{order_id}", responses=error_responses(NotOrderOwnerException))
+@requires(require_active, order_owner)
+async def delete_order(
+    order_id: UUID,
+    user: UserModel = Depends(get_current_user),
+) -> None:
+    """The body runs only for an active user who owns the order."""
+    await controller.delete(order_id)
+```
+
+The user parameter is found by annotation (`user_param=` breaks a tie), and a guard's non-`None` return replaces the user the body sees — which is how `require_active` narrows `UserT | None` to `UserT`.
+
+Misuse is caught in three places: `TempestPermissionError` at import time (no guard, wrong arity, `async` guard on a sync function, no user parameter), `GuardContractWarning` at call time (a guard raising outside the `AppException` hierarchy, or returning `False` instead of denying), and `tempest permissions --check` in CI, which reads the same contract statically.
+
+```bash
+tempest permissions --check            # exit 1 on any error
+tempest permissions --check --strict   # fail on warnings too
+```
+
+`tempest openapi-errors` reads the `@requires` guards too, so a guard's exception shows up as `undocumented` on the route until it is declared. Full walkthrough: [Permission guards](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/en/recipes/permission-guards/).
+
+---
+
 ## Conventions
 
 - **Layered architecture**: routers → controllers → services → repositories. Never skip layers.

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/docs/architecture.en.md

@@ -163,6 +163,31 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `update(id, data)` | `service.update` | Same. |
 | `delete(id)` | `service.delete` | Same. |
 
+!!! tip "Typing the `update` payload end to end"
+    The 3rd generic parameter is the update schema, and it must be the **same** on both layers: a service declared as `BaseService[Repo, Resp, MyUpdateSchema]` fits `BaseController[MyService, Resp, MyUpdateSchema]`. Omit the 3rd parameter on either one and it falls back to the `BaseSchema` default, leaving `update`'s `data` loosely typed.
+
+    ```python
+    from tempest_fastapi_sdk import BaseController, BaseService
+
+    from src.db.repositories import CoinPackRepository
+    from src.schemas import CoinPackResponseSchema, CoinPackUpdateSchema
+
+
+    class CoinPackService(
+        BaseService[CoinPackRepository, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Service typed over the concrete update schema."""
+
+
+    class CoinPackController(
+        BaseController[CoinPackService, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Controller repeating the same update schema."""
+    ```
+
+    !!! warning "Requires 0.167.1+"
+        On earlier versions this pair failed type checking with `Type parameter "UpdateT@BaseService" is invariant, but "CoinPackUpdateSchema" is not the same as "BaseSchema"` — `ServiceT`'s bound pinned that invariant parameter to `BaseSchema`. Fixed in 0.167.1; nothing changes at runtime.
+
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.
 
 ```python

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/docs/architecture.md

@@ -163,6 +163,31 @@ O que você herda ao subclassear `BaseController[ServiceT, ResponseT]`:
 | `update(id, data)` | `service.update` | Igual. |
 | `delete(id)` | `service.delete` | Igual. |
 
+!!! tip "Tipando o payload de `update` ponta a ponta"
+    O 3º parâmetro genérico é o schema de update, e ele precisa ser o **mesmo** nas duas camadas: um service declarado como `BaseService[Repo, Resp, MeuUpdateSchema]` encaixa em `BaseController[MeuService, Resp, MeuUpdateSchema]`. Omitir o 3º parâmetro em qualquer uma delas cai no default `BaseSchema`, e o `data` de `update` chega sem tipo preciso.
+
+    ```python
+    from tempest_fastapi_sdk import BaseController, BaseService
+
+    from src.db.repositories import CoinPackRepository
+    from src.schemas import CoinPackResponseSchema, CoinPackUpdateSchema
+
+
+    class CoinPackService(
+        BaseService[CoinPackRepository, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Service tipado sobre o schema de update concreto."""
+
+
+    class CoinPackController(
+        BaseController[CoinPackService, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Controller que repete o mesmo schema de update."""
+    ```
+
+    !!! warning "Requer 0.167.1+"
+        Em versões anteriores esse par falhava no type check com `Type parameter "UpdateT@BaseService" is invariant, but "CoinPackUpdateSchema" is not the same as "BaseSchema"` — o bound de `ServiceT` deixava o parâmetro invariante fixado em `BaseSchema`. Corrigido em 0.167.1; nada muda em runtime.
+
 Quando um caso de uso precisa de regras de domínio, sobrescreva o método herdado no service. Quando um caso de uso precisa coordenar mais de um service, sobrescreva o método herdado (ou adicione um novo) no controller. O router nunca cresce — ele só depende do controller.
 
 ```python

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/docs/recipes/authz.en.md

@@ -183,3 +183,10 @@ The mixin delegates to the global registry (`default_registry`).
 - Superuser and static set are injectable via `PermissionRegistry`.
 - Rules match by exact string or wildcard (`order.*`, `*`).
 - `PermissionMixin` gives you `await user.has_perm(...)`.
+
+!!! tip "Already holding the user?"
+    When the check is an invariant on the user itself (active, admin, owner of
+    the resource) rather than a question for the registry,
+    [`@requires`](permission-guards.md) runs `(user) -> user | None` guards at
+    any layer — and a guard may call `check_permission(...)` to combine both
+    approaches.

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/docs/recipes/authz.md

@@ -182,3 +182,10 @@ O mixin delega ao registry global (`default_registry`).
 - Superusuário e conjunto estático são injetáveis via `PermissionRegistry`.
 - Regras batem por string exata ou wildcard (`order.*`, `*`).
 - `PermissionMixin` dá o `await user.has_perm(...)`.
+
+!!! tip "Já tem o usuário na mão?"
+    Quando a checagem é uma invariante sobre o próprio usuário (ativo, admin,
+    dono do recurso) e não uma pergunta ao registry, o
+    [`@requires`](permission-guards.md) roda guards `(user) -> user | None` em
+    qualquer camada — e um guard pode chamar `check_permission(...)` para
+    combinar as duas abordagens.

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/docs/recipes/cli.en.md

@@ -504,6 +504,37 @@ Details and limitations in the [Errors in OpenAPI »](openapi-errors.md) recipe.
 
 ---
 
+### Permission guards — `tempest permissions`
+
+Reads the `@requires` guard contract straight off the source (`ast`, without
+importing the application) and reports what the decorator cannot see at import
+time:
+
+```bash
+tempest permissions                    # informative report (exit 0)
+tempest permissions --check            # exit 1 on any error (CI gate)
+tempest permissions --check --strict   # fail on warnings too
+tempest permissions --path src --path libs
+```
+
+```text
+src/api/routers/orders.py:41  delete_order
+  error: guard-foreign-exception: guard 'order_owner' raises ValueError, which is
+    not an AppException subclass; the API layer answers it as HTTP 500 without an
+    error code
+2 finding(s), 1 error(s).
+```
+
+Errors: a guard raising outside the `AppException` hierarchy, a predicate-style
+guard (`-> bool`), wrong arity, an `async` guard on a sync function, a route with
+no user parameter. Warnings: a guard that never denies, a missing annotation, a
+guard the checker could not resolve (lambda, duplicated name, definition outside
+the scanned paths).
+
+Details in the [Permission guards (`@requires`) »](permission-guards.md) recipe.
+
+---
+
 ### Integration client — `tempest openapi-client`
 
 Generates Pydantic schemas + a typed HTTP client from a third party's OpenAPI

{tempest_fastapi_sdk-0.166.1 → tempest_fastapi_sdk-0.167.1}/docs/recipes/cli.md

@@ -502,6 +502,36 @@ Detalhes e limitações na receita [Erros no OpenAPI »](openapi-errors.md).
 
 ---
 
+### Guards de permissão — `tempest permissions`
+
+Lê o contrato dos guards do `@requires` direto do código-fonte (`ast`, sem
+importar a aplicação) e reporta o que o decorator não consegue ver em tempo de
+import:
+
+```bash
+tempest permissions                    # relatório informativo (exit 0)
+tempest permissions --check            # exit 1 se houver erro (gate de CI)
+tempest permissions --check --strict   # falha também nos warnings
+tempest permissions --path src --path libs
+```
+
+```text
+src/api/routers/orders.py:41  delete_order
+  error: guard-foreign-exception: guard 'order_owner' raises ValueError, which is
+    not an AppException subclass; the API layer answers it as HTTP 500 without an
+    error code
+2 finding(s), 1 error(s).
+```
+
+Erros: guard que levanta fora da hierarquia `AppException`, guard-predicado
+(`-> bool`), aridade errada, guard `async` em função sync, rota sem parâmetro de
+usuário. Warnings: guard que nunca nega, anotação faltando, guard que o checker
+não conseguiu resolver (lambda, nome duplicado, definição fora do escopo).
+
+Detalhes na receita [Guards de permissão (`@requires`) »](permission-guards.md).
+
+---
+
 ### Cliente de integração — `tempest openapi-client`
 
 Gera schemas Pydantic + um cliente HTTP tipado a partir da especificação OpenAPI