4.10.0 — 2026-05-18

← 4.10.1 | 4.9.3 → | ↑ 4.x series

Added

Adapters - Keycloak

• Batch UMA Permission Checks - Added check_permissions_batch to KeycloakPort and AsyncKeycloakPort (and their adapter implementations) for evaluating multiple (resource, scope) pairs in a single UMA call.
  • Returns a frozenset[tuple[str, str]] containing only the granted pairs from the requested set.
  • Sync implementation wraps KeycloakOpenID.uma_permissions; async implementation wraps a_uma_permissions.
  • Cached with ttl_cache_decorator(ttl_seconds=30, maxsize=200) (sync) and alru_cache(ttl=30, maxsize=200) ( async) to avoid redundant Keycloak round-trips.
  • Existing check_permissions now documents check_permissions_batch as the preferred entry point when multiple pairs must be checked per request.

Changed

Adapters - Keycloak

• get_userinfo Trusts UserInfo Endpoint - Removed the local validate_token precheck from both sync and async get_userinfo implementations.
  • The Keycloak UserInfo endpoint already validates the token server-side, so the extra local validation was redundant and an unnecessary network round-trip.
  • Dropped the now-unused InvalidTokenError import from archipy/adapters/keycloak/adapters.py.
  • Docstrings updated to call out that UserInfo handles validation.

Helpers - Keycloak Utils

• Shared Adapter Instances - KeycloakUtils._get_keycloak_adapter and _get_async_keycloak_adapter now delegate to process-wide @cached factories (_shared_sync_adapter, _shared_async_adapter) instead of constructing a new adapter per decorator invocation.
• Authorization Pipeline Consolidation - Extracted the gRPC auth-decorator authorization flow into reusable helpers and used the new batch permission API throughout.
  • Added _authorize_sync / _authorize_async helpers that validate the token, fetch token info, retrieve UserInfo, perform optional resource-ownership checks, enforce role requirements, and run batch permission checks.
  • Added _extract_roles, _check_resource_access, and _build_auth_context helpers to centralize role aggregation (realm + client), ownership/admin checks, and AuthContext construction.
  • Role enforcement now uses local set operations against UserInfo claims (issuperset / isdisjoint) rather than issuing separate has_all_roles / has_any_of_roles calls.
  • Permission enforcement uses check_permissions_batch and surfaces missing pairs via the missing_permissions field in PermissionDeniedError.additional_data.
  • BaseError instances raised inside async wrappers are re-raised after the optional gRPC abort, preventing them from being wrapped into InternalError.

Helpers - Decorators

• Sharper Tracing Decorator Generics - capture_transaction, capture_span, async_capture_transaction, and async_capture_span now bind their generic F to local _Function / _AsyncFunction Protocol classes that require a __name__ attribute, replacing the looser Callable[..., Any] bound and giving callers better type narrowing on decorated functions.