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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.166.1
+Version: 0.167.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
@@ -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.0}/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.0}/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.0}/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.0}/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.0}/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

tempest_fastapi_sdk-0.167.0/docs/recipes/permission-guards.en.md

@@ -0,0 +1,320 @@
+# Permission guards (`@requires`)
+
+You already hold the user — it came from a dependency, or from a service
+parameter — and you want to assert an invariant before the function body runs:
+"must be active", "must own the order", "must be an admin".
+
+`@requires` does that with plain functions: no framework, no registry, no magic
+strings. 🚀
+
+## The problem
+
+Without a decorator, the check becomes noise at the top of every function:
+
+```python
+async def delete_order(order_id: UUID, user: UserModel | None) -> None:
+    if user is None:
+        raise UnauthorizedException(message="Authentication required")
+    if not user.is_active:
+        raise ForbiddenException(message="User account is inactive")
+    if order_id not in user.owned_orders:
+        raise ForbiddenException(message="Not the order owner")
+    ...
+```
+
+Three problems: repetition across every route, authorization mixed into business
+logic, and nothing stops someone from writing `if not allowed: return None`
+instead of raising — the route answers 200 on a denial.
+
+## The solution in 2 steps
+
+### 1. Write the guard
+
+A guard is an ordinary function: it **takes the user**, **returns the user** (or
+`None`) and **denies by raising** an `AppException`.
+
+```python
+from tempest_fastapi_sdk import ForbiddenException
+
+from src.db.models import UserModel
+
+
+def order_owner(user: UserModel) -> UserModel:
+    """Assert the user owns the order under edit.
+
+    Args:
+        user (UserModel): The authenticated user.
+
+    Returns:
+        UserModel: The same user.
+
+    Raises:
+        NotOrderOwnerException: When the user does not own the order.
+    """
+    if not user.owns_current_order:
+        raise NotOrderOwnerException()
+    return user
+```
+
+!!! warning "A guard denies by raising, never by returning `False`"
+    `return False` denies **nothing** — `@requires` ignores the value and warns
+    with `GuardContractWarning`, and `tempest permissions` reports
+    `guard-returns-bool` as an error. The reason is error standardization:
+    raising an `AppException` gets you the HTTP status, the `code` and the
+    `{detail, code, details}` envelope for free from the SDK handlers.
+
+### 2. Decorate the function
+
+```python
+from uuid import UUID
+
+from fastapi import Depends
+from tempest_fastapi_sdk import error_responses, requires
+from tempest_fastapi_sdk.auth import require_active
+
+from src.api.dependencies import get_current_user
+from src.api.guards import order_owner
+from src.core.exceptions import NotOrderOwnerException
+from src.db.models import UserModel
+
+
+@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:
+    """Delete an order the caller owns.
+
+    Args:
+        order_id (UUID): The order to delete.
+        user (UserModel): The authenticated, active, owning user.
+    """
+    await controller.delete(order_id)
+```
+
+That is it. Guards run left to right before the body; the body runs only if all
+of them pass.
+
+!!! tip "Decorator order"
+    `@requires` goes **below** the route decorator. The router must register the
+    already-guarded function.
+
+## Where the user comes from
+
+`@requires` finds the user parameter **by annotation**: the one whose type is a
+`BaseModel` / `BaseUserModel` subclass. Nothing to configure in the common case.
+
+When the signature holds more than one user, point at the right one:
+
+```python
+@requires(can_ban_users, user_param="target")
+async def ban_user(
+    actor: UserModel = Depends(get_current_user),
+    target: UserModel = Depends(get_target_user),
+) -> None:
+    """Ban the target user.
+
+    Args:
+        actor (UserModel): The moderator performing the ban.
+        target (UserModel): The user being banned.
+    """
+    ...
+```
+
+??? info "Technical details — annotation resolution"
+    The order is: an explicit `user_param=`; then the single parameter whose
+    annotation resolves to a user model; then — only when no annotation resolved
+    to one — the single parameter whose name is in `USER_PARAM_NAMES`
+    (`user`, `current_user`, `actor`, `requester`, `principal`) or whose textual
+    annotation mentions `User`. That last step exists because
+    `from __future__ import annotations` plus a `TYPE_CHECKING` import leaves the
+    annotation impossible to evaluate at decoration time.
+
+    When nothing resolves — or two candidates tie — the import fails with
+    `TempestPermissionError`. Better an application that refuses to start than
+    one running a check that never fires.
+
+## The guard's return narrows the type
+
+A guard that returns the user replaces the user seen by the next guard **and by
+the function body**. That is how the SDK guards
+(`require_authenticated` / `require_active` / `require_admin`) turn
+`UserT | None` into `UserT`:
+
+```python
+@requires(require_active)
+async def me(user: UserModel | None = Depends(get_current_user_soft)) -> UserModel:
+    """Return the authenticated user.
+
+    Args:
+        user (UserModel | None): Filled by the soft dependency; guaranteed
+            non-None inside the body.
+
+    Returns:
+        UserModel: The active user.
+    """
+    return user
+```
+
+Returning `None` is allowed and means "I did not touch the user".
+
+## Works at any layer
+
+Nothing here depends on FastAPI. The same decorator works on a controller or a
+service, sync or `async`:
+
+```python
+from tempest_fastapi_sdk import requires
+
+from src.api.guards import order_owner
+from src.db.models import UserModel
+
+
+class OrderService:
+    """Business logic for orders."""
+
+    @requires(order_owner)
+    async def delete(self, order_id: UUID, user: UserModel) -> None:
+        """Delete an order the caller owns.
+
+        Args:
+            order_id (UUID): The order to delete.
+            user (UserModel): The owning user.
+        """
+        await self.repository.delete(order_id)
+```
+
+`async` guards may only decorate `async` functions — otherwise the coroutine
+would never be awaited, so the import fails with `TempestPermissionError`.
+
+## The linter catches your mistakes
+
+Two layers, because each sees what the other cannot.
+
+### At import time — `TempestPermissionError`
+
+The decorator validates while the module is imported. The application **does not
+start** with:
+
+| Situation | Message |
+| --- | --- |
+| `@requires()` with no guard | `needs at least one guard` |
+| non-callable guard | `is not callable` |
+| guard with 2 required params | `takes 2 required params, expected 1 (user)` |
+| `async` guard on a sync function | `is async but ... is not` |
+| no user parameter | `no parameter annotated with a user model` |
+| two user parameters | `several parameters are user models` |
+
+### At call time — `GuardContractWarning`
+
+What only shows up while running: a guard raising `ValueError` (the API would
+answer 500 with no `code`) and a guard returning `False` (the denial would be
+ignored). `@requires` **warns** and lets the original exception propagate — it
+must not change the outcome of a call it is only observing.
+
+!!! tip "Turn it into an error in tests"
+    Run the suite with
+    `-W error::tempest_fastapi_sdk.authz.GuardContractWarning` (or
+    `filterwarnings = ["error"]` in `pyproject.toml`) and a guard outside the
+    contract fails the test instead of becoming a log line.
+
+### In CI — `tempest permissions`
+
+What neither layer reaches: a guard whose `raise` sits behind an `if` no test
+exercises, or a guard that is never imported. The command reads the contract off
+the source with `ast`, without importing the application:
+
+```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
+  warning: guard-missing-annotation: guard 'order_owner' has no return annotation
+2 finding(s), 1 error(s).
+```
+
+The codes it reports:
+
+| Code | Severity | What it means |
+| --- | --- | --- |
+| `no-guards` | error | `@requires()` with no guard: everything passes |
+| `user-param-missing` | error | no parameter is a user model |
+| `user-param-ambiguous` | error | several candidates, no `user_param=` |
+| `guard-arity` | error | the guard does not take exactly one parameter |
+| `guard-async-in-sync` | error | `async` guard on a sync function |
+| `guard-returns-bool` | error | predicate-style guard: its `False` is ignored |
+| `guard-foreign-exception` | error | raises outside the `AppException` hierarchy |
+| `guard-never-denies` | warning | nothing in the call graph raises |
+| `guard-missing-annotation` | warning | parameter or return unannotated |
+| `guard-return-type` | warning | return is neither the user, `None`, nor their union |
+| `guard-unresolved` | warning | the guard is a lambda, lives outside the scanned paths, or its name maps to several definitions |
+
+!!! note "Reports instead of guessing"
+    A guard whose name exists in two modules becomes `guard-unresolved`, not a
+    check against the wrong definition. Same policy as `openapi-errors`:
+    over-reporting is acceptable, a confident wrong verdict is not.
+
+## OpenAPI error-docs integration
+
+A guard denies by raising, so its exception is as reachable as that of any
+function the body calls. `tempest openapi-errors` reads the `@requires` guards
+when building the reachable set:
+
+```bash
+tempest openapi-errors --check
+```
+
+```text
+src/api/routers/orders.py:41  DELETE /orders/{order_id}
+  undocumented: NotOrderOwnerException
+```
+
+`--fix` writes `responses=error_responses(NotOrderOwnerException)` into the
+route, like any other exception in the flow. Details in the
+[OpenAPI errors »](openapi-errors.md) recipe.
+
+## Auditing a route's guards
+
+```python
+from tempest_fastapi_sdk import declared_guards, guarded_user_param
+
+assert declared_guards(delete_order) == (require_active, order_owner)
+assert guarded_user_param(delete_order) == "user"
+```
+
+Handy in a test asserting that every write route carries at least one guard.
+
+## `@requires` vs. the other authorization tools
+
+| Tool | Question it answers | Where it lives |
+| --- | --- | --- |
+| `make_permission_dependency` | "does the token carry `orders:write`?" | route dependency, before the handler |
+| `has_perm` / `make_permission_checker` | "may this user act on this object?" | registry of `(user, obj) -> bool` rules |
+| `@requires` | "does this user pass these invariants?" | any function that already receives the user |
+
+The three compose: a guard may call `check_permission(user, "order.delete",
+obj=order)` and pull the whole registry inside `@requires`.
+
+## Recap
+
+- A **guard** is `(user) -> user | None` that denies by raising an
+  `AppException`.
+- `@requires(g1, g2)` runs the guards in order, below the route decorator.
+- The user parameter comes from the annotation; `user_param=` breaks ties.
+- A non-`None` return replaces the user — that is how the type narrows.
+- Works on routers, controllers and services, sync or `async`.
+- Misuse: `TempestPermissionError` at import, `GuardContractWarning` at call
+  time, `tempest permissions --check` in CI.
+- Guard exceptions reach `error_responses(...)` through
+  `tempest openapi-errors`.