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

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

@@ -5,6 +5,97 @@ 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
+that is not this repository. Three things only that setting can show.
+
+### Fixed
+
+- **`--fix` now formats with the target project's ruff config.** The scratch
+  file it hands to ruff was created in the system temp directory, where ruff
+  finds no `pyproject.toml` and falls back to its own defaults. A project on
+  `line-length = 120`, or with custom `isort` sections, got output formatted to
+  ruff's defaults — which its own `ruff format --check` then rejected, on a file
+  the command had just written. The scratch file is now created next to the file
+  being rewritten, so settings resolve the same way they do for the project.
+  `normalize()` takes a `near=` directory for this.
+- **Silent skip of that formatting is now reported.** `ruff` was resolved as
+  "on `PATH`, else `uv run ruff`", and neither branch was verified. Invoked by
+  absolute path from a venv (`/…/.venv/bin/tempest`), that venv's `bin/` is not
+  on `PATH`, so resolution fell through to `uv run ruff` — which exists but
+  cannot run outside a uv project, failing silently under `check=False`. The
+  write then emitted an unsorted import and an over-long decorator with no hint
+  why. New `ruff_runner()` adds `python -m ruff` for the importable-but-not-on-
+  `PATH` case, probes every candidate with `--version`, and the command prints a
+  `note:` line pointing at `tempest fix` when none works.
+- **The `docs`-marked tests no longer trust a stale `site/`.** Both fixtures
+  rebuilt only when the built file was *absent*, so an out-of-date local build
+  was read as current: 14 tests failed on a clean `main` naming pages and
+  symbols that were in fact present. CI never saw it, having no `site/` at all.
+  A single `built_site` fixture now lives in `tests/conftest.py` and rebuilds
+  whenever `mkdocs.yml`, `docs/` or `mkdocs_hooks/` is newer than the output.
+
+### Added
+
+- **`ruff_runner()`** in `tempest_fastapi_sdk.cli.openapi_fix` — returns a
+  probed argv prefix that runs ruff, or `None`. Exported for callers that want
+  to make the same "can I format this?" decision.
+
 ## [0.166.0] — 2026-07-25
 
 ### Added

{tempest_fastapi_sdk-0.166.0 → 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.0 → tempest_fastapi_sdk-0.167.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.166.0
+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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.166.0 → tempest_fastapi_sdk-0.167.0}/docs/recipes/openapi-errors.en.md

@@ -534,6 +534,28 @@ honored.
     through `ruff check --select I --fix` and `ruff format`, so a new import
     lands in sorted position and a wrapped decorator comes out formatted.
 
+    That formatting uses **your project's config**, not ruff's defaults: the
+    temporary file is created next to the file being rewritten, and ruff
+    resolves its settings by walking up the directory tree. Your `line-length`
+    and your `isort` sections apply, so what the command writes passes your own
+    CI's `ruff format --check`.
+
+!!! note "With no ruff, it says so instead of pretending"
+    Normalization needs a ruff that actually runs — on `PATH`, importable in the
+    current interpreter (`python -m ruff`), or through `uv run ruff`. Every
+    candidate is probed with `--version` before being used. When none works the
+    write still happens (the splice is already valid Python) and the command
+    tells you what it skipped:
+
+    ```text
+    note: no working ruff found, so the new import stays where it was spliced
+    and a long decorator is not wrapped. Run `tempest fix` afterwards to sort
+    and format.
+    ```
+
+    Without that line you would find out from your CI's `ruff check` failing on
+    a file this very command just wrote.
+
 !!! check "A clean git tree is required"
     With a clean tree, `git diff` is the review and `git checkout` is the undo —
     the real safety net for a tool that edits code you wrote. With pending

{tempest_fastapi_sdk-0.166.0 → tempest_fastapi_sdk-0.167.0}/docs/recipes/openapi-errors.md

@@ -529,6 +529,28 @@ presente prova que o projeto optou por esse estilo; aí ele é respeitado.
     `ruff check --select I --fix` e `ruff format`, então o import novo cai na
     posição ordenada e o decorator quebrado em linhas sai formatado.
 
+    A formatação usa **a config do seu projeto**, não os defaults do ruff: o
+    arquivo temporário é criado ao lado do arquivo reescrito, e o ruff resolve
+    settings subindo a árvore de diretórios. Seu `line-length` e suas seções de
+    `isort` valem, então o que o comando escreve passa no `ruff format --check`
+    do seu próprio CI.
+
+!!! note "Sem ruff, ele avisa em vez de fingir"
+    A normalização depende de um ruff que realmente rode — no `PATH`, importável
+    no interpretador atual (`python -m ruff`), ou via `uv run ruff`. Cada
+    candidato é testado com `--version` antes de ser usado. Não achando nenhum, a
+    gravação acontece de todo jeito (o splice já é Python válido) e o comando diz
+    o que ficou de fora:
+
+    ```text
+    note: no working ruff found, so the new import stays where it was spliced
+    and a long decorator is not wrapped. Run `tempest fix` afterwards to sort
+    and format.
+    ```
+
+    Sem esse aviso você descobriria pelo `ruff check` do CI reclamando de um
+    arquivo que o próprio comando acabou de escrever.
+
 !!! check "Árvore git limpa obrigatória"
     Com a árvore limpa, `git diff` é a revisão e `git checkout` é o desfazer —
     a rede de segurança real de uma ferramenta que edita código que você