PyPI - tempest-fastapi-sdk - Versions diffs - 0.167.2__tar.gz → 0.168.0__tar.gz - Mend

tempest-fastapi-sdk 0.167.2tar.gz → 0.168.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (766) hide show

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/CHANGELOG.md RENAMED Viewed

@@ -5,6 +5,54 @@ 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.168.0] — 2026-07-26
+Permission guards gain injected metadata: one generic guard, a specific check
+per call site.
+### Added
+- **A guard may declare a second parameter `meta: dict[str, Any]`.** That is
+  what turns `manager_only` / `auditor_only` / `admin_only` into one
+  `has_role(user, meta)` whose call sites declare
+  `@requires(has_role, meta={"role": "manager"})`. One-parameter guards are
+  untouched — the second argument is passed only to guards that declare it, so
+  both shapes mix freely in the same decoration.
+- **`requires(..., meta=...)`** — literal metadata, copied at decoration time,
+  so a later mutation of the passed mapping cannot change what the route
+  enforces. Must be a `Mapping[str, Any]`; anything else is a
+  `TempestPermissionError` at import.
+- **`requires(..., include_args=True)`** — merges the arguments the decorated
+  function was called with into the same mapping, so an ownership guard reads
+  `meta["order_id"]` without the route handing it over. The user parameter is
+  excluded (the guard already receives it), a parameter the caller omitted
+  contributes its default so the guard sees the values the body will run with,
+  a default that is a framework injection marker (`Depends(...)`) is dropped
+  rather than passed as a value, and a `meta=` literal wins a name clash with
+  an argument — the decoration is the explicit declaration. The mapping is
+  fresh per call and shared by that call's guards, so one guard may write a key
+  the next one reads without anything leaking into the next request.
+- **`guard_metadata(fn)`** — reads the `meta=` literals off a decorated
+  function, next to `declared_guards` / `guarded_user_param`. Exported from
+  `tempest_fastapi_sdk` and `tempest_fastapi_sdk.authz`.
+- **Four static checks in `tempest permissions`:** `meta-unused` (error — the
+  decoration passes `meta=` / `include_args=True` but no guard declares a
+  second parameter; held back when a guard in that decoration could not be
+  resolved, since it may be the consumer), `guard-meta-missing` (warning — a
+  two-parameter guard whose decoration supplies no metadata reads an empty
+  dict), `guard-meta-annotation` (warning — the metadata parameter is annotated
+  as something that cannot hold a `dict[str, Any]`) and `meta-key-collision`
+  (warning — a `meta=` key shadows a parameter name under `include_args=True`,
+  so that argument never reaches the guard).
+### Changed
+- **`guard-arity` accepts one or two required parameters.** A guard taking
+  `(user, meta)` used to be rejected at import (`expected 1 (user)`); the
+  contract is now one *or* two, and the message reads
+  `expected 1 (user) or 2 (user, meta)`. Three or more is still an error. No
+  existing single-parameter guard changes behavior.
 ## [0.167.2] — 2026-07-26
 Documentation layout only — no code change, no API change.

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/CLAUDE.md RENAMED Viewed

@@ -92,7 +92,15 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   `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`.
+  route. **Metadata (v0.168.0):** a guard may declare a 2nd param
+  `meta: dict[str, Any]` — `meta={...}` literals fixed at decoration plus
+  `include_args=True` merging the call's args (user excluded, omitted params
+  contribute defaults, `Depends(...)` markers dropped, `meta=` wins a name
+  clash); one-param guards untouched; `TempestPermissionError` when `meta=`
+  isn't a mapping or nothing consumes it; `guard_metadata(fn)` reads the
+  literals; new static codes `meta-unused` (error), `guard-meta-missing`/
+  `guard-meta-annotation`/`meta-key-collision` (warnings). 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 /

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.167.2
+Version: 0.168.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
@@ -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`, `requires` (guard decorator `(user) -> user | None`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param`, `TempestPermissionError`, `GuardContractWarning` |
+| `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`, optional `meta: dict[str, Any]` second parameter via `meta=` / `include_args=`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param` / `guard_metadata`, `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` |
@@ -4169,6 +4169,27 @@ async def delete_order(
 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`.
+A guard may declare a second parameter to receive a `dict[str, Any]` of metadata, which is what turns one generic guard into a specific check per call site — `meta=` carries literals fixed at decoration, `include_args=True` merges the call's own arguments:
+```python
+def has_role(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Deny unless the user holds the role the route declared."""
+    if meta["role"] not in user.roles:
+        raise MissingRoleException(role=meta["role"])
+    return user
+@requires(has_role, meta={"role": "manager"})
+async def close_month(user: UserModel = Depends(get_current_user)) -> None: ...
+@requires(order_owner, include_args=True)      # guard reads meta["order_id"]
+async def delete_order(
+    order_id: UUID,
+    user: UserModel = Depends(get_current_user),
+) -> None: ...
+```
 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_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/README.md RENAMED Viewed

@@ -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`, `requires` (guard decorator `(user) -> user | None`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param`, `TempestPermissionError`, `GuardContractWarning` |
+| `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`, optional `meta: dict[str, Any]` second parameter via `meta=` / `include_args=`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param` / `guard_metadata`, `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` |
@@ -4023,6 +4023,27 @@ async def delete_order(
 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`.
+A guard may declare a second parameter to receive a `dict[str, Any]` of metadata, which is what turns one generic guard into a specific check per call site — `meta=` carries literals fixed at decoration, `include_args=True` merges the call's own arguments:
+```python
+def has_role(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Deny unless the user holds the role the route declared."""
+    if meta["role"] not in user.roles:
+        raise MissingRoleException(role=meta["role"])
+    return user
+@requires(has_role, meta={"role": "manager"})
+async def close_month(user: UserModel = Depends(get_current_user)) -> None: ...
+@requires(order_owner, include_args=True)      # guard reads meta["order_id"]
+async def delete_order(
+    order_id: UUID,
+    user: UserModel = Depends(get_current_user),
+) -> None: ...
+```
 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_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/recipes/index.en.md RENAMED Viewed

@@ -320,7 +320,7 @@ come back here to plug in each capability as you need it.
 | **[Security »](security.md)** | `AttemptThrottle`, opaque-token helpers, `HardenedStaticFiles`, security headers |
 | **[Brazilian helpers »](br-helpers.md)** | CPF / CNPJ / CEP / phone validation + normalization |
 | **[Object-level permissions »](authz.md)** | `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry`, `make_permission_checker`, `PermissionMixin` |
-| **[Permission guards (@requires) »](permission-guards.md)** | `@requires` plus `(user) -> user` guards, `TempestPermissionError`, `GuardContractWarning`, `tempest permissions --check` |
+| **[Permission guards (@requires) »](permission-guards.md)** | `@requires` plus `(user) -> user` guards (with an optional `meta: dict[str, Any]` via `meta=` / `include_args=`), `TempestPermissionError`, `GuardContractWarning`, `tempest permissions --check` |
 | **[Introspection auth (resource server) »](introspection-auth.md)** | `IntrospectionAuth` — validate an opaque bearer by asking the upstream identity provider |
 | **[Geolocation (distance + travel time) »](geo.md)** | `haversine_km`, `estimate_travel`, `OSRMBackend`, `NominatimBackend`, `GeoPointMixin` / `GeoRepositoryMixin` |
 | **[Self-hosted generative AI »](genai.md)** | `probe_hardware` / `can_run`, `TextGenerator`, `Embedder`, RAG (web + PDF), audio (STT/TTS), `make_genai_router` |

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/recipes/index.md RENAMED Viewed

@@ -319,7 +319,7 @@ aqui pra plugar cada capacidade conforme precisar.
 | **[Segurança »](security.md)** | `AttemptThrottle`, helpers de token opaco, `HardenedStaticFiles`, headers de segurança |
 | **[Helpers brasileiros »](br-helpers.md)** | validação + normalização de CPF / CNPJ / CEP / telefone |
 | **[Permissões object-level »](authz.md)** | `permission` (decorator de regra), `has_perm` / `check_permission`, `PermissionRegistry`, `make_permission_checker`, `PermissionMixin` |
-| **[Guards de permissão (@requires) »](permission-guards.md)** | `@requires` + guards `(user) -> user`, `TempestPermissionError`, `GuardContractWarning`, `tempest permissions --check` |
+| **[Guards de permissão (@requires) »](permission-guards.md)** | `@requires` + guards `(user) -> user` (com `meta: dict[str, Any]` opcional via `meta=` / `include_args=`), `TempestPermissionError`, `GuardContractWarning`, `tempest permissions --check` |
 | **[Auth por introspecção (resource server) »](introspection-auth.md)** | `IntrospectionAuth` — validar bearer opaco perguntando ao provedor de identidade upstream |
 | **[Geolocalização (distância + tempo) »](geo.md)** | `haversine_km`, `estimate_travel`, `OSRMBackend`, `NominatimBackend`, `GeoPointMixin` / `GeoRepositoryMixin` |
 | **[IA generativa self-hosted »](genai.md)** | `probe_hardware` / `can_run`, `TextGenerator`, `Embedder`, RAG (web + PDF), áudio (STT/TTS), `make_genai_router` |

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/recipes/permission-guards.en.md RENAMED Viewed

@@ -162,6 +162,114 @@ async def me(user: UserModel | None = Depends(get_current_user_soft)) -> UserMod
 Returning `None` is allowed and means "I did not touch the user".
+## Metadata: one generic guard, many call sites
+A guard may declare a **second parameter** `meta: dict[str, Any]`. That is what turns a generic guard into a specific check per route — instead of writing `manager_only`, `auditor_only`, `admin_only`, you write `has_role` once and each call site says which role it requires.
+```python
+from typing import Any
+from tempest_fastapi_sdk import ForbiddenException, requires
+from src.db.models import UserModel
+def has_role(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Assert the user holds the role the route declared.
+    Args:
+        user (UserModel): The authenticated user.
+        meta (dict[str, Any]): Metadata injected by ``@requires``.
+    Returns:
+        UserModel: The same user.
+    Raises:
+        MissingRoleException: When the declared role is missing.
+    """
+    if meta["role"] not in user.roles:
+        raise MissingRoleException(role=meta["role"])
+    return user
+@router.post("/reports/close-month")
+@requires(has_role, meta={"role": "manager"})
+async def close_month(user: UserModel = Depends(get_current_user)) -> None:
+    """Close the accounting month.
+    Args:
+        user (UserModel): The authenticated manager.
+    """
+    ...
+```
+One-parameter guards behave exactly as before — the second argument only goes to guards that declare it. You can mix both in the same decoration.
+### `include_args=True`: the guard sees the call's arguments
+`meta=` carries literals fixed at decoration. When the check depends on the **resource** of the request, turn on `include_args=True` and the call's arguments (path params, body, other dependencies) join the same dict:
+```python
+def order_owner(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Assert the user owns the order named by the metadata.
+    Args:
+        user (UserModel): The authenticated user.
+        meta (dict[str, Any]): Metadata injected by ``@requires``.
+    Returns:
+        UserModel: The same user.
+    Raises:
+        NotOrderOwnerException: When the user does not own the order.
+    """
+    if meta["order_id"] not in user.order_ids:
+        raise NotOrderOwnerException()
+    return user
+@router.delete("/orders/{order_id}")
+@requires(require_active, order_owner, include_args=True)
+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.
+    """
+    ...
+```
+The guard receives `{"order_id": UUID(...)}` without the route handing anything over.
+!!! info "Merge rules"
+    - The **user is excluded** — the guard already receives it as the first parameter.
+    - A parameter the caller left out contributes its **default**, so the guard sees the values the body will run with. A default that is an injection marker (`Depends(...)`) is **dropped**, never handed over as a value.
+    - A key declared in `meta=` **wins** over an argument of the same name: the decoration is the explicit declaration, the argument is ambient data. `tempest permissions` reports it (`meta-key-collision`), because that argument never reaches the guard.
+    - The dict is **fresh per call** and shared by that call's guards — one guard may write a key the next one reads, and nothing leaks into the next request.
+### Configuration errors
+| Situation | What happens |
+| --- | --- |
+| `meta=` is not a mapping | `TempestPermissionError` at import |
+| `meta=` / `include_args=True` with no two-parameter guard | `TempestPermissionError` at import — the configuration would do nothing |
+| a two-parameter guard and a decoration with no `meta=`/`include_args=` | runs with `{}`; `tempest permissions` reports `guard-meta-missing` |
+| a guard with 3+ required parameters | `TempestPermissionError` at import (`expected 1 (user) or 2 (user, meta)`) |
+To audit what a route declared:
+```python
+from tempest_fastapi_sdk import guard_metadata
+assert guard_metadata(close_month) == {"role": "manager"}
+```
+`guard_metadata` returns only the `meta=` literals — whatever `include_args=True` merges exists per call and cannot be read off the function object.
 ## Works at any layer
 Nothing here depends on FastAPI. The same decorator works on a controller or a
@@ -208,6 +316,7 @@ start** with:
 | `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` |
+| `meta=`/`include_args=` with no consumer | `no guard declares a second parameter` |
 ### At call time — `GuardContractWarning`
@@ -251,13 +360,17 @@ The codes it reports:
 | `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-arity` | error | the guard takes neither 1 parameter (user) nor 2 (user, meta) |
+| `meta-unused` | error | `meta=`/`include_args=` with no guard to receive it |
 | `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-meta-missing` | warning | the guard asks for metadata and the decoration supplies none |
+| `guard-meta-annotation` | warning | the 2nd parameter is annotated as something that cannot hold `dict[str, Any]` |
+| `meta-key-collision` | warning | a `meta=` key shadows a parameter under `include_args=True` |
 | `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"
@@ -308,10 +421,12 @@ obj=order)` and pull the whole registry inside `@requires`.
 ## Recap
-- A **guard** is `(user) -> user | None` that denies by raising an
-  `AppException`.
+- A **guard** is `(user) -> user | None` — or `(user, meta) -> 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.
+- `meta={...}` parameterizes a generic guard; `include_args=True` hands the
+  call's arguments to it.
 - 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

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/recipes/permission-guards.md RENAMED Viewed

@@ -163,6 +163,114 @@ async def me(user: UserModel | None = Depends(get_current_user_soft)) -> UserMod
 Devolver `None` é permitido e significa "não mexi no usuário".
+## Metadata: um guard genérico, vários call sites
+Um guard pode declarar um **segundo parâmetro** `meta: dict[str, Any]`. É isso que transforma um guard genérico numa checagem específica por rota — em vez de escrever `manager_only`, `auditor_only`, `admin_only`, você escreve `has_role` uma vez e cada call site diz qual papel exige.
+```python
+from typing import Any
+from tempest_fastapi_sdk import ForbiddenException, requires
+from src.db.models import UserModel
+def has_role(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Assert the user holds the role the route declared.
+    Args:
+        user (UserModel): The authenticated user.
+        meta (dict[str, Any]): Metadata injected by ``@requires``.
+    Returns:
+        UserModel: The same user.
+    Raises:
+        MissingRoleException: When the declared role is missing.
+    """
+    if meta["role"] not in user.roles:
+        raise MissingRoleException(role=meta["role"])
+    return user
+@router.post("/reports/close-month")
+@requires(has_role, meta={"role": "manager"})
+async def close_month(user: UserModel = Depends(get_current_user)) -> None:
+    """Close the accounting month.
+    Args:
+        user (UserModel): The authenticated manager.
+    """
+    ...
+```
+Guards de **um** parâmetro continuam exatamente como antes — o segundo argumento só vai para quem o declara. Você pode misturar os dois numa mesma decoração.
+### `include_args=True`: o guard vê os argumentos da chamada
+`meta=` carrega literais fixados na decoração. Quando a checagem depende do **recurso** da requisição, ligue `include_args=True` e os argumentos da chamada (path params, body, outras dependências) entram no mesmo dicionário:
+```python
+def order_owner(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Assert the user owns the order named by the metadata.
+    Args:
+        user (UserModel): The authenticated user.
+        meta (dict[str, Any]): Metadata injected by ``@requires``.
+    Returns:
+        UserModel: The same user.
+    Raises:
+        NotOrderOwnerException: When the user does not own the order.
+    """
+    if meta["order_id"] not in user.order_ids:
+        raise NotOrderOwnerException()
+    return user
+@router.delete("/orders/{order_id}")
+@requires(require_active, order_owner, include_args=True)
+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.
+    """
+    ...
+```
+O guard recebe `{"order_id": UUID(...)}` sem a rota precisar repassar nada.
+!!! info "Regras da mesclagem"
+    - O **usuário sai** do dicionário — o guard já o recebe no primeiro parâmetro.
+    - Parâmetro que o chamador omitiu contribui com o **default**, então o guard vê os valores com que o corpo vai rodar. Default que é marcador de injeção (`Depends(...)`) é **descartado**, nunca entregue como valor.
+    - Chave declarada em `meta=` **ganha** de um argumento com o mesmo nome: a decoração é a declaração explícita, o argumento é dado ambiente. O `tempest permissions` avisa (`meta-key-collision`) quando isso acontece, porque o argumento nunca chega ao guard.
+    - O dicionário é **novo em cada chamada** e compartilhado pelos guards daquela chamada — um guard pode gravar uma chave que o próximo lê, e nada vaza para a próxima requisição.
+### Erros de configuração
+| Situação | O que acontece |
+| --- | --- |
+| `meta=` não é um mapping | `TempestPermissionError` no import |
+| `meta=` / `include_args=True` sem nenhum guard de 2 parâmetros | `TempestPermissionError` no import — a configuração não faria nada |
+| guard de 2 parâmetros e decoração sem `meta=`/`include_args=` | roda com `{}`; `tempest permissions` avisa `guard-meta-missing` |
+| guard com 3+ parâmetros obrigatórios | `TempestPermissionError` no import (`expected 1 (user) or 2 (user, meta)`) |
+Para auditar o que uma rota declarou:
+```python
+from tempest_fastapi_sdk import guard_metadata
+assert guard_metadata(close_month) == {"role": "manager"}
+```
+`guard_metadata` devolve só os literais de `meta=` — o que `include_args=True` mescla existe por chamada e não dá para ler do objeto função.
 ## Funciona em qualquer camada
 Nada aqui depende do FastAPI. O mesmo decorator vale para controller e service,
@@ -209,6 +317,7 @@ com:
 | guard `async` em função sync | `is async but ... is not` |
 | nenhum parâmetro de usuário | `no parameter annotated with a user model` |
 | dois parâmetros de usuário | `several parameters are user models` |
+| `meta=`/`include_args=` sem consumidor | `no guard declares a second parameter` |
 ### Em tempo de chamada — `GuardContractWarning`
@@ -251,13 +360,17 @@ Códigos reportados:
 | `no-guards` | erro | `@requires()` sem guard: tudo passa |
 | `user-param-missing` | erro | nenhum parâmetro é modelo de usuário |
 | `user-param-ambiguous` | erro | vários candidatos, sem `user_param=` |
-| `guard-arity` | erro | guard não recebe exatamente um parâmetro |
+| `guard-arity` | erro | guard não recebe 1 parâmetro (user) nem 2 (user, meta) |
+| `meta-unused` | erro | `meta=`/`include_args=` sem nenhum guard que receba |
 | `guard-async-in-sync` | erro | guard `async` em função sync |
 | `guard-returns-bool` | erro | guard-predicado: o `False` é ignorado |
 | `guard-foreign-exception` | erro | levanta fora da hierarquia `AppException` |
 | `guard-never-denies` | warning | nada no grafo de chamadas levanta |
 | `guard-missing-annotation` | warning | parâmetro ou retorno sem anotação |
 | `guard-return-type` | warning | retorno não é o usuário, `None` ou a união |
+| `guard-meta-missing` | warning | guard pede metadata e a decoração não passa nenhuma |
+| `guard-meta-annotation` | warning | 2º parâmetro anotado como algo que não recebe `dict[str, Any]` |
+| `meta-key-collision` | warning | chave de `meta=` encobre um parâmetro sob `include_args=True` |
 | `guard-unresolved` | warning | guard é lambda, está fora do escopo ou o nome bate com várias definições |
 !!! note "Reporta em vez de adivinhar"
@@ -308,9 +421,10 @@ obj=order)` e ganhar o registry inteiro dentro do `@requires`.
 ## Recap
-- **Guard** = `(user) -> user | None` que nega levantando `AppException`.
+- **Guard** = `(user) -> user | None` — ou `(user, meta) -> user | None` — que nega levantando `AppException`.
 - `@requires(g1, g2)` roda os guards na ordem, abaixo do decorator de rota.
 - O parâmetro do usuário sai da anotação; `user_param=` desempata.
+- `meta={...}` parametriza um guard genérico; `include_args=True` entrega os argumentos da chamada ao guard.
 - Retorno não-`None` substitui o usuário — é assim que o tipo estreita.
 - Funciona em router, controller e service, sync ou `async`.
 - Erro de uso: `TempestPermissionError` no import, `GuardContractWarning` na

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/reference.md RENAMED Viewed

@@ -235,6 +235,7 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ::: tempest_fastapi_sdk.authz.requires.requires
 ::: tempest_fastapi_sdk.authz.requires.Guard
 ::: tempest_fastapi_sdk.authz.requires.declared_guards
+::: tempest_fastapi_sdk.authz.requires.guard_metadata
 ::: tempest_fastapi_sdk.authz.requires.guarded_user_param
 ::: tempest_fastapi_sdk.authz.requires.TempestPermissionError
 ::: tempest_fastapi_sdk.authz.requires.GuardContractWarning

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/roadmap.en.md RENAMED Viewed

@@ -131,6 +131,17 @@ GraphQL/gRPC (REST by decision).
 !!! note "This roadmap is honest, not aspirational"
     Items past the next cuts only land on the changelog when business pressure pulls them. This page is refreshed on every release — if something belongs here and isn't, open an issue.
+## Shipped in v0.168.0
+Permission guards with metadata:
+| Feature | Status | Where |
+|---------|--------|-------|
+| **Second parameter `meta: dict[str, Any]`** | ✅ v0.168 | A guard may declare a second parameter and receive metadata, which turns a generic guard into a route-specific check: write `has_role` once and let each call site declare `meta={"role": "manager"}`. One-parameter guards are untouched — the second argument only goes to guards that declare it. [Reference »](recipes/permission-guards.md) |
+| **`include_args=True`** | ✅ v0.168 | Merges the call's arguments (path params, body, other dependencies) into the same dict, so an ownership guard reads `meta["order_id"]` without the route handing anything over. User excluded, omitted parameters contribute their default, `Depends(...)` markers dropped, `meta=` literals winning over same-named arguments. |
+| **Misuse still caught at import** | ✅ v0.168 | `TempestPermissionError` when `meta=` is not a mapping, when `meta=`/`include_args=` have no guard to receive them, and when a guard asks for 3+ parameters. `guard_metadata(fn)` exposes the declared literals. |
+| **New static checks** | ✅ v0.168 | `tempest permissions` gained `meta-unused` (error), `guard-meta-missing`, `guard-meta-annotation` and `meta-key-collision` (warnings); `guard-arity` now accepts 1 or 2 parameters. The `meta-unused` verdict is held back when a guard in the decoration could not be resolved. |
 ## Shipped in v0.167.0
 Permission guards — decorator plus a two-layer linter:

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/docs/roadmap.md RENAMED Viewed

@@ -131,6 +131,17 @@ GraphQL/gRPC (REST por decisão).
 !!! note "O roadmap é honesto, não aspiracional"
     Itens fora dos próximos cuts só vão pro changelog quando a pressão de negócio puxar. Esta página é atualizada a cada release — se algo deveria estar aqui e não está, abra uma issue.
+## Entregue na v0.168.0
+Guards de permissão com metadata:
+| Feature | Status | Onde |
+|---------|--------|------|
+| **Segundo parâmetro `meta: dict[str, Any]`** | ✅ v0.168 | Um guard pode declarar um segundo parâmetro e receber metadata, o que transforma um guard genérico em checagem específica por rota: escreve-se `has_role` uma vez e cada call site declara `meta={"role": "manager"}`. Guards de um parâmetro seguem intactos — o segundo argumento só vai para quem o declara. [Referência »](recipes/permission-guards.md) |
+| **`include_args=True`** | ✅ v0.168 | Mescla os argumentos da chamada (path params, body, outras dependências) no mesmo dicionário, então um guard de posse lê `meta["order_id"]` sem a rota repassar nada. Usuário fora, default de parâmetro omitido incluído, marcador `Depends(...)` descartado, literal de `meta=` ganhando de argumento homônimo. |
+| **Erro de uso ainda no import** | ✅ v0.168 | `TempestPermissionError` quando `meta=` não é mapping, quando `meta=`/`include_args=` não têm nenhum guard que receba, e quando o guard pede 3+ parâmetros. `guard_metadata(fn)` expõe os literais declarados. |
+| **Checagem estática nova** | ✅ v0.168 | `tempest permissions` ganhou `meta-unused` (erro), `guard-meta-missing`, `guard-meta-annotation` e `meta-key-collision` (warnings); `guard-arity` passou a aceitar 1 ou 2 parâmetros. O veredito `meta-unused` é retido quando algum guard da decoração não pôde ser resolvido. |
 ## Entregue na v0.167.0
 Guards de permissão — decorator + linter em duas camadas:

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.167.2"
+version = "0.168.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/tempest_fastapi_sdk/__init__.py RENAMED Viewed

@@ -161,6 +161,7 @@ from tempest_fastapi_sdk.authz import (
     check_permission,
     declared_guards,
     default_registry,
+    guard_metadata,
     guarded_user_param,
     has_perm,
     make_permission_checker,
@@ -444,7 +445,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
-__version__: str = "0.167.2"
+__version__: str = "0.168.0"
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -768,6 +769,7 @@ __all__: list[str] = [
     "get_client_ip_from_scope",
     "get_request_id",
     "get_state",
+    "guard_metadata",
     "guarded_user_param",
     "has_perm",
     "hash_opaque_token",

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.0}/tempest_fastapi_sdk/authz/__init__.py RENAMED Viewed

@@ -32,6 +32,7 @@ from tempest_fastapi_sdk.authz.requires import (
     TempestPermissionError as TempestPermissionError,
 )
 from tempest_fastapi_sdk.authz.requires import declared_guards as declared_guards
+from tempest_fastapi_sdk.authz.requires import guard_metadata as guard_metadata
 from tempest_fastapi_sdk.authz.requires import guarded_user_param as guarded_user_param
 from tempest_fastapi_sdk.authz.requires import requires as requires
@@ -48,6 +49,7 @@ __all__: list[str] = [
     "check_permission",
     "declared_guards",
     "default_registry",
+    "guard_metadata",
     "guarded_user_param",
     "has_perm",
     "make_permission_checker",

tempest-fastapi-sdk 0.167.2__tar.gz → 0.168.0__tar.gz

tempest-fastapi-sdk 0.167.2tar.gz → 0.168.0tar.gz