Skip to content

xtr_security_http.decorator

The route-surface decorators: the firewall's authorization markers.

:class:~xtr_security_http.decorator.is_granted.IsGranted, :class:~xtr_security_http.decorator.current_user.CurrentUser, :class:~xtr_security_http.decorator.current_token.CurrentToken and :class:~xtr_security_http.decorator.is_csrf_token_valid.IsCsrfTokenValid are the markers a route carries — pure metadata, each delegating its enforcement to an injectable service in :mod:xtr_security_http.resolver — and :class:~xtr_security_http.decorator.is_granted_context.IsGrantedContext is the context a closure attribute is handed. :class:~xtr_security_http.decorator.firewall_listener_order.FirewallListenerOrder declares where a firewall listener stands among the ones it shares a priority with.

SOURCE_HEADER module-attribute

SOURCE_HEADER: Final = 4

Read the presented value from a header.

SOURCE_PAYLOAD module-attribute

SOURCE_PAYLOAD: Final = 1

Read the presented value from the request payload: the JSON body, else the form.

SOURCE_QUERY module-attribute

SOURCE_QUERY: Final = 2

Read the presented value from the query string.

CurrentToken

CurrentToken(*, optional: bool = False)

Bases: Depends

Injects the token the request authenticated into an endpoint parameter.

Used as Annotated[TokenInterface, CurrentToken()] — for an endpoint that decides something itself off the roles or the attributes authentication settled on. The marker is pure metadata; the reading of the request's security state happens in the injectable :class:~xtr_security_http.resolver.security_token_resolver.SecurityTokenResolver the thin dependency delegates to.

By default the parameter must have a token: an anonymous request raises :class:~xtr_security_core.exception.AuthenticationCredentialsNotFoundError, which becomes a 401. Passing optional=True — for a parameter typed TokenInterface | None — returns None for an anonymous request instead. The dependency never appears in the generated schema.

Attributes:

  • optional (bool) –

    Whether an anonymous request yields None instead of raising.

Inject the current token, optionally nullable.

CurrentUser

CurrentUser(user_class: type | tuple[type, ...] | None = None, *, optional: bool = False, disabled: bool = False)

Bases: Depends

Injects the current user into an endpoint parameter.

Used as Annotated[User, CurrentUser()]. The marker is pure metadata — what the argument wants — and the reading of the request's security state happens in the injectable :class:~xtr_security_http.resolver.user_value_resolver.UserValueResolver the thin dependency delegates to.

By default the parameter must have a user: an anonymous request raises :class:~xtr_security_core.exception.AuthenticationCredentialsNotFoundError, which becomes a 401. Passing optional=True — for a parameter typed User | None — returns None for an anonymous request instead. When user_class is given (one class, or several as a tuple for a union), a user of another class raises :class:~xtr_security_core.exception.UnsupportedUserError. Passing disabled=True switches the resolution off for this one parameter — the dependency yields None without reading the request — for an application that enables the resolver globally but excludes a route.

(The web framework does not hand a dependency the annotation of the parameter it fills, so nullability and the expected class are stated on the marker rather than read from User | None.)

The dependency never appears in the generated schema.

Attributes:

  • optional (bool) –

    Whether an anonymous request yields None instead of raising.

  • user_class (type | tuple[type, ...] | None) –

    The class (or tuple of classes) a user must be, or None to accept any.

  • disabled (bool) –

    Whether this marker's resolution is switched off.

Inject the current user, optionally typed, nullable, and disablable.

FirewallListenerOrder

FirewallListenerOrder(*, before: type | str | Sequence[type | str] = (), after: type | str | Sequence[type | str] = ())

Declares the firewall listeners a listener runs before or after.

Used on a listener class::

@FirewallListenerOrder(after=ContextListener, before=AccessListener)
class TwoFactorListener(AbstractListener): ...

A listener's get_priority() is kept: these constraints only reorder the listeners that share it, and one that would need a listener to cross a priority fails the build instead of silently moving it. This way a listener cannot displace the chain's own ordering by mistake — it can only settle how it stands against the ones it runs beside.

A target is a listener class, its "module:Class" name, or the qualifier it runs under in the firewall's chain. One naming a listener that is not in the chain is ignored — the package adding it may simply not be installed.

Declare the neighbours, a single target or a sequence of them per direction.

before property

before: tuple[type | str, ...]

Return the listeners this one runs before, as classes, names or qualifiers.

after property

after: tuple[type | str, ...]

Return the listeners this one runs after, as classes, names or qualifiers.

IsCsrfTokenValid

IsCsrfTokenValid(token_id: str, *, token_key: str = '_token', methods: str | Sequence[str] = (), token_source: int = SOURCE_PAYLOAD)

Bases: Depends

Requires the request to present the value minted for a token id.

Used as a dependency or a decorator, like :class:~xtr_security_http.decorator.is_granted.IsGranted. The marker is pure metadata — which token id a route proves, where the request carries the value, which methods it applies to — and the checking happens in the injectable :class:~xtr_security_http.resolver.csrf_token_checker.CsrfTokenChecker the thin dependency delegates to, which hands the presented value to the token manager.

A request that presents no value, or one the manager does not vouch for, is refused with a 403. The sources are a bitmask: the default reads the payload (the JSON body, else the parsed form); SOURCE_QUERY and SOURCE_HEADER widen it, and several combine — the first source named that carries a value wins. A marker that names no method applies to every one; a marker that names GET also answers HEAD.

Attributes:

  • token_id (str) –

    The id the token is known under — what it guards.

  • token_key (str) –

    The key the request carries the value under.

  • methods (tuple[str, ...]) –

    The (upper-cased) methods the check applies to; empty is all.

  • token_source (int) –

    The bitmask of the sources the value is read from.

Require the value minted for token_id, read as token_source says.

IsGranted

IsGranted(attribute: str | Callable[..., bool | Awaitable[bool]], subject: str | Callable[..., object] | None = None, *, message: str | None = None, status_code: int | None = None, exception_code: int | None = None, methods: str | Sequence[str] = (), consume_security_scopes: bool = False)

Bases: Depends

Requires an attribute over a subject before the endpoint runs.

Written as a dependency or a decorator:

@router.delete("/books/{isbn}")
@IsGranted("ROLE_ADMIN")                          # below the route decorator
async def delete_book(isbn: str) -> None: ...


@router.put("/books/{isbn}", dependencies=[IsGranted("BOOK_EDIT", subject=load_book)])
async def edit(book: Annotated[Book, Depends(load_book)]) -> Book: ...

The marker is pure metadata — what must be granted, over what, and how a denial answers — and the deciding happens in the injectable :class:~xtr_security_http.resolver.is_granted_checker.IsGrantedChecker the thin dependency delegates to, which runs the attribute through the access-decision machinery.

The attribute is a string a voter matches, or a callable (IsGrantedContext, subject) -> bool the closure voter runs. The subject is None, the name of a path parameter, or a callable used as a FastAPI dependency — resolved once per request and shared with the endpoint. A denial raises an :class:~xtr_security_core.exception.AccessDeniedError, which the firewall's exception listener turns into 401 or 403; a status_code answers with that status directly instead. It requires a firewall to have run; without one the check is made against the anonymous token.

methods limits the check to those (upper-cased; GET extends to HEAD); a marker that names none applies to every method. The security scopes a route declared natively are ignored unless consume_security_scopes=True: opted in, the request's accumulated scopes are decided through the voter stack too, each one an attribute that must be granted; without it they stay declaration and documentation, and adding this marker to a chain never silently turns them into enforcement.

Attributes:

  • attribute (object) –

    The attribute required.

  • subject (object) –

    How the subject is obtained, or None.

  • message (str | None) –

    The denial message.

  • status_code (int | None) –

    The status a denial answers with directly, or None.

  • exception_code (int | None) –

    A code recorded on the marker for the caller that catches the denial.

  • methods (tuple[str, ...]) –

    The (upper-cased) methods the check applies to; empty is all.

  • consume_security_scopes (bool) –

    Whether the request's accumulated security scopes are decided too.

Require attribute over subject before the endpoint runs.

IsGrantedContext

IsGrantedContext(token: TokenInterface, user: UserInterface | None, authorization_checker: AuthorizationCheckerInterface)

Bases: AuthorizationCheckerInterface

The token, its user, and an authorization checker to ask further questions.

A closure attribute (see :class:~xtr_security_core.authorization.voter.closure_voter.ClosureVoter) receives one of these and the subject. It has the token and its user to reason about directly, :meth:is_granted to ask a nested question for the same token — "may this token edit this book?" — and shortcuts for the authentication-strength questions.

Attributes:

Record the token, its user, and the checker nested questions go to.

token property

token: TokenInterface

The token the decision is being made for.

user property

user: UserInterface | None

The token's user, or None when nobody is authenticated.

is_granted async

is_granted(attribute: object, subject: object = None, access_decision: AccessDecision | None = None) -> bool

Answer a nested access question for the same token.

is_authenticated async

is_authenticated() -> bool

Tell whether the token is authenticated.

is_authenticated_fully async

is_authenticated_fully() -> bool

Tell whether the token is fully authenticated.

is_authenticated_recently async

is_authenticated_recently() -> bool

Tell whether the user authenticated recently.

is_authenticated_very_recently async

is_authenticated_very_recently() -> bool

Tell whether the user authenticated very recently.

is_impersonator async

is_impersonator() -> bool

Tell whether the user is impersonating another user.

firewall_listener_order_of

firewall_listener_order_of(listener_class: type) -> FirewallListenerOrder | None

Return what @FirewallListenerOrder recorded on listener_class, or None.

Only the class's own declaration is read: a subclass states its place in the chain itself, or inherits none.