xtr_security_core.exception ¶
Every error the security core raises.
All of them derive from :class:SecurityError, so one except catches
anything authentication or authorization can go wrong with, and a narrower one
handles a single cause. Each carries the data a caller needs as typed
attributes rather than forcing a message to be parsed. The HTTP edge adds its
own errors that still derive from these.
AccessDeniedError ¶
AccessDeniedError(message: str = 'Access Denied.', *, attributes: Sequence[object] = (), subject: object = None, access_decision: AccessDecision | None = None)
Bases: SecurityError
Authorization refused a known caller.
Distinct from an authentication failure: who is calling was established;
what they asked to do was not permitted. When the caller turns out not to
be fully authenticated, an entry point may answer this with a challenge
instead of a plain refusal; otherwise it becomes a 403. When a decision is
passed, its :attr:~xtr_security_core.authorization.access_decision.AccessDecision.message
— the denying voters' reasons — is appended to the error message.
Attributes:
-
attributes(tuple[object, ...]) –The attributes that were checked (one, in this library).
-
subject(object) –The subject the attributes were checked against, if any.
-
access_decision(AccessDecision | None) –The decision that refused, with its votes, if built.
Record what was checked, against what, and the decision that refused.
AccountExpiredError ¶
AccountStatusError ¶
AccountStatusError(user: UserInterface | None = None, message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
Authentication is refused because of the account's own state.
The credentials were correct: the account is disabled, locked, or expired.
A user checker raises one of the subclasses; whether the client is told the
real reason or only that its credentials failed is decided by the exposure
level (see :func:~xtr_security_http.authentication.is_sensitive).
A session keeps none of the user: rebuilt from one, the error names no user.
Attributes:
-
user(UserInterface | None) –The user whose account state refused authentication.
Record the user whose account state refused authentication.
from_session
classmethod
¶
Rebuild the error a session kept, naming no user — the session kept none.
AuthenticationCredentialsNotFoundError ¶
AuthenticationCredentialsNotFoundError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
No authentication credentials were found in the request.
Distinct from rejected credentials: nothing was presented at all, so the caller is anonymous where authentication was required.
AuthenticationError ¶
AuthenticationError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: SecurityError
Authentication failed: who is calling could not be established.
An authentication error separates two messages. The one passed to
:class:Exception is internal — it may name a user, a claim or a reason,
and belongs in a log, never in a response. :attr:message_key is the safe
public text a client may see, and :attr:message_data the values a
presentation layer substitutes into it. Keeping them apart is what lets a
failure be logged in full while the client learns only that credentials
were rejected.
A failed login that redirects keeps its error in the session for the page
that renders the form again, and a session keeps the public half only:
:meth:to_session answers the key and the data, and :meth:from_session
rebuilds an error of the same class whose internal message is the key —
the internal message never reaches the session store.
Attributes:
-
message_key(str) –Safe, public text describing the failure.
-
message_data(dict[str, object]) –Values a presentation layer may substitute into the key.
Record the internal message and the safe public key and data.
Parameters:
-
message(str | None, default:None) –The internal message; defaults to the public key.
-
message_key(str | None, default:None) –The safe public text; defaults to :attr:
MESSAGE_KEY. -
message_data(Mapping[str, object] | None, default:None) –Values for the public key.
get_message_data ¶
Return the values a presentation layer substitutes into the key.
to_session ¶
Return the public half of this error, for a session to keep.
The key, and the entries of the data that come back from JSON exactly as they went in; an entry that would not is left out rather than refusing the error, since the data only decorates the key. The internal message is not part of it: it may name a user or a reason, and belongs in a log, never in a store outside the process.
from_session
classmethod
¶
Rebuild an error a session kept, as this class, from its public half.
The class's constructor is not run — a subclass's asks for what the
session never kept, a user or a status — so a subclass carrying more
than the key and the data overrides this to settle the rest. The
rebuilt error's internal message is the key: str(error) reads it.
AuthenticationServiceError ¶
AuthenticationServiceError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A service authentication relies on failed.
A database that answers a user lookup, a remote key set that verifies a token — when one of these is unreachable, the caller is neither accepted nor rejected: the attempt could not be completed at all.
BadCredentialsError ¶
BadCredentialsError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
The credentials presented were rejected.
The public catch-all of authentication: a wrong password, a malformed token, or a masked sensitive failure all surface as this, so a client learns only that its credentials did not work.
BadMethodCallError ¶
Bases: SecurityError
A method was called that this object refuses by design.
The anonymous token answers every question about itself but accepts no user, attribute or authentication proof; the placeholder provider of a firewall that has none loads nobody. Calling such a method is a mistake in the caller, not a state to recover from.
CookieTheftError ¶
CookieTheftError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A remember-me cookie carried a value that was already spent.
A remember-me value is one-time: presenting it rotates it. The same value arriving twice means the cookie was copied — stolen — and the series it belongs to is dropped so the thief and the owner are both logged out.
CredentialsExpiredError ¶
CustomUserMessageAccountStatusError ¶
CustomUserMessageAccountStatusError(message_key: str, *, user: UserInterface | None = None, message_data: Mapping[str, object] | None = None, message: str | None = None)
Bases: AccountStatusError
An account-status failure whose public text is chosen at the raise site.
Deliberately shown to the client rather than masked: a checker with a safe, specific reason ("your subscription has lapsed") raises this with that reason as the message key.
Record the public message key and the values it substitutes.
CustomUserMessageAuthenticationError ¶
CustomUserMessageAuthenticationError(message_key: str, *, message_data: Mapping[str, object] | None = None, message: str | None = None)
Bases: AuthenticationError
An authentication failure whose public text is chosen at the raise site.
Where the ordinary errors mask their cause, this one is deliberately shown to the client: an authenticator that has a safe, specific reason to give ("your account is not yet activated") raises this with that reason as the message key.
Record the public message key and the values it substitutes.
DisabledError ¶
ExpiredSignatureError ¶
Bases: SecurityError
A signature is sound but past its expiry.
The secret matched and the covered fields did not change; only the moment the hash was valid until has passed. A flow that distinguishes this from an invalid signature can tell the caller to start over rather than that its link or cookie was never issued.
InsufficientAuthenticationError ¶
InsufficientAuthenticationError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
Authentication succeeded, but not to the level this resource needs.
Raised when access is denied to a caller who is not fully authenticated: the answer is to authenticate more strongly, not to be forbidden outright.
InvalidArgumentError ¶
Bases: SecurityError, ValueError
A declaration, configuration or call was malformed.
A decision asked for on several attributes at once, an attribute read from
a token that carries none, a firewall referring to a provider that is not
configured — mistakes caught where they are made. Also a
:class:ValueError, so code guarding its configuration with
except ValueError keeps working.
InvalidSignatureError ¶
Bases: SecurityError
A signature matches neither the secret nor the fields it claims.
The hash was forged, or something it covers changed: another user, a rotated password, parameters it was not bound with. Nothing about the request is sound, so nothing is said about why.
LockedError ¶
SecurityError ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything authentication or authorization can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.
TooManyLoginAttemptsAuthenticationError ¶
Bases: AuthenticationError
Login is refused because the caller failed too many times.
A throttling listener raises this once the failed attempts cross its limit. The public key says how long the caller must wait, when the limiter could say: the wait is the only thing the caller can act on.
Rebuilt from a session, it reads the wait back from its own data, where
the key's %minutes% keeps it.
Attributes:
-
threshold(int | None) –The minutes the caller must wait, or
Nonewhen the wait is not quantified.
Record the wait and compose the public key from it.
Parameters:
-
threshold(int | None, default:None) –The minutes the caller must wait, if the limiter could count them.
from_session
classmethod
¶
Rebuild the error a session kept, the wait read back from %minutes%.
UnsupportedUserError ¶
Bases: SecurityError, TypeError
A user of the wrong class reached a provider, checker or resolver.
Also a :class:TypeError: the object is not the kind of user the code was
configured to work with, a mistake in wiring rather than in credentials.
UserNotFoundError ¶
UserNotFoundError(user_identifier: str | None = None, message: str | None = None, *, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError, LookupError
No user matched the identifier presented.
Also a :class:LookupError, so a provider's caller may treat a missing
user like any other failed lookup. Its public key is the one
:class:~xtr_security_core.exception.bad_credentials_error.BadCredentialsError
carries — "Invalid credentials." — rather than anything naming the
identifier: a distinct key would tell a client that a user does not exist,
a way to enumerate accounts, so the identifier stays on
:attr:user_identifier for logs alone.
A session keeps none of the identifier, for the same reason: rebuilt from one, the error names no identifier.
Attributes:
-
user_identifier(str | None) –The identifier that matched no user.
Record the identifier that matched no user.
from_session
classmethod
¶
Rebuild the error a session kept, naming no identifier — the session kept none.