Skip to content

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

AccountExpiredError(user: UserInterface | None = None, message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AccountStatusError

The account has expired and may no longer authenticate.

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

from_session(message_key: str, message_data: Mapping[str, object]) -> Self

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_key

get_message_key() -> str

Return the safe public text for this error.

get_message_data

get_message_data() -> Mapping[str, object]

Return the values a presentation layer substitutes into the key.

to_session

to_session() -> dict[str, object]

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

from_session(message_key: str, message_data: Mapping[str, object]) -> Self

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

CredentialsExpiredError(user: UserInterface | None = None, message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AccountStatusError

The account's credentials have expired and must be renewed.

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

DisabledError(user: UserInterface | None = None, message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AccountStatusError

The account has been disabled and may not authenticate.

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

LockedError(user: UserInterface | None = None, message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)

Bases: AccountStatusError

The account is locked and may not authenticate.

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

TooManyLoginAttemptsAuthenticationError(threshold: int | None = None)

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 None when 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

from_session(message_key: str, message_data: Mapping[str, object]) -> Self

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

from_session(message_key: str, message_data: Mapping[str, object]) -> Self

Rebuild the error a session kept, naming no identifier — the session kept none.