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_PAYLOAD
module-attribute
¶
Read the presented value from the request payload: the JSON body, else the form.
SOURCE_QUERY
module-attribute
¶
Read the presented value from the query string.
CurrentToken ¶
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
Noneinstead 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
Noneinstead of raising. -
user_class(type | tuple[type, ...] | None) –The class (or tuple of classes) a user must be, or
Noneto 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.
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:
-
token(TokenInterface) –The token the decision is being made for.
-
user(UserInterface | None) –The token's user, or
Nonewhen nobody is authenticated.
Record the token, its user, and the checker nested questions go to.
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_fully
async
¶
Tell whether the token is fully authenticated.
is_authenticated_recently
async
¶
Tell whether the user authenticated recently.
is_authenticated_very_recently
async
¶
Tell whether the user authenticated very recently.
is_impersonator
async
¶
Tell whether the user is impersonating another user.
firewall_listener_order_of ¶
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.