xtr_security_http.exception ¶
The errors the HTTP edge adds to the security core's.
Each derives from a core error — :class:~xtr_security_core.exception.SecurityError
or :class:~xtr_security_core.exception.AuthenticationError — so one
except SecurityError still catches everything the family raises.
The one base here that is not itself an error is the login-link marker:
never raised, only worn by the refusals a link earns so the flow catches
them together.
ExpiredLoginLinkError ¶
Bases: ExpiredSignatureError, InvalidLoginLinkErrorInterface
A login link whose hash is sound but whose moment has passed.
Derives from the core's expired-signature error — a link's hash is a signature, and everything the core says about one past its expiry holds here — wearing the marker so the flow that refused the link catches it with the rest.
ImpersonationError ¶
Bases: SecurityError, RuntimeError
A generated impersonation address was asked for and could not be built.
Also a :class:RuntimeError. The causes are configuration gaps: no
firewall with a user switch for the request, a switch that asks for a
cross-site request forgery token while no manager was given to mint
one, or a dedicated path configured as a route name, which no routing
component here can resolve.
InvalidAccessTokenError ¶
InvalidAccessTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A bearer access token could not be trusted.
The token was present but malformed, expired, signed with the wrong key,
or otherwise not verifiable. A protected resource answers such a token
with a challenge naming invalid_token.
InvalidCsrfTokenError ¶
InvalidCsrfTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A cross-site request forgery token was presented but could not be vouched for.
The passport carried a token badge, and the value the request presented with it did not match what the token manager stored under the badge's id — or the request presented no value at all. The login the badge was meant to guard is refused: a request the page that rendered the form did not ask for cannot authenticate through it.
InvalidLoginLinkAuthenticationError ¶
InvalidLoginLinkAuthenticationError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A login through a link failed because the link does not check out.
The flow's one authentication-layer answer to every refusal the handler raises: the caller learns the link was invalid or expired, and nothing else — which parameter failed the link's reading stays in the error the handler already raised.
InvalidLoginLinkError ¶
Bases: SecurityError, RuntimeError, InvalidLoginLinkErrorInterface
A request presented a login link the handler cannot accept.
The link's own reading failed — a parameter missing or malformed, a
hash that verifies under no secret, a user the provider does not
know — before any authentication ran; the error names the link, not
a login attempt. The authentication layer's answer to it is
:class:~xtr_security_http.exception.InvalidLoginLinkAuthenticationError.
InvalidLoginLinkErrorInterface ¶
Bases: Exception
An error saying a login link does not check out.
A handler refuses a link for more than one reason — a parameter it cannot read, a hash no secret signs, a moment that has passed — and each refusal raises its own error; the authenticator that hands the link to the handler catches them all with this one base and answers with the single authentication error of its own.
The marker is a class the refused errors inherit, not a Protocol
a runtime check would answer True for regardless: it is caught,
and a catch must name a base the errors actually derive from.
InvalidSessionStrategyError ¶
Bases: SecurityError, RuntimeError
A session strategy was asked to act under a name that is none of its own.
The strategy names — none, migrate, invalidate — are the
application's configuration, carried as a string; one that matches
no name is heard the first time the strategy runs, carrying the name
as it was configured. Also a :class:RuntimeError.
Record the unknown strategy name.
Parameters:
-
strategy(str) –The configured strategy name that matched none of the strategy's own.
get_strategy ¶
Return the configured strategy name that matched none of the strategy's own.
LogoutError ¶
Bases: SecurityError, RuntimeError
A request reached the logout step and failed its proof.
Also a :class:RuntimeError. The one cause today is a cross-site
request forgery token that does not check out: a request that names
the logout path must still prove it came from a page the application
rendered, and one that cannot is refused rather than logged out.
MissingSessionError ¶
Bases: SecurityError, RuntimeError
A session strategy found no session on the request it was asked to move.
The session a strategy moves is the one the request's security state
carries — the context listener's park, built from the request through
the session storage. A request whose state holds none reached a
strategy through a caller that ran no stateful machinery for it, and
the strategy refuses to guess: rotating a session that does not exist
would read as protection while protecting nothing. Also a
:class:RuntimeError.
MissingStateBagError ¶
Bases: SecurityError, RuntimeError
A listener was asked to support a request that carries no state bag.
The caller that runs a firewall's chain parks the kernel event's state
bag on the request it hands to each listener's supports, so a
listener that needs the flow's per-request carrier reaches the one the
event carries. A request without one reached the chain through a caller
that skipped that step, and the listener refuses to guess: a silently
fresh carrier would park the flow's handoffs where the event's readers
never find them. Also a :class:RuntimeError.
OidcInvalidGrantError ¶
OidcInvalidGrantError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
An OIDC provider no longer honors a grant, for good.
The one token endpoint error of RFC 6749, Section 5.2 a caller has to tell apart from every other failure: the grant is gone for good — the refresh token expired, was revoked, or was issued to another client — where an unreachable provider or a server error only means the request may be tried again. A caller that catches this knows not to.
OidcSessionEndedError ¶
OidcSessionEndedError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
The reason a login is deauthenticated when a back-channel logout ended its provider session.
The session is not invalidated, as it can hold the logins of other firewalls. An application that wants it invalidated — the way a front-channel logout does by default — does it from the deauthentication event, by reading this error off the reason the event carries.
UnknownFirewallError ¶
Bases: SecurityError, LookupError
No firewall is configured under the name asked for.
Also a :class:LookupError. Names the firewalls that are configured, so
the mistake — a typo, a firewall never declared — is plain from the error.
Attributes:
-
name(str) –The name that matched no firewall.
-
configured(tuple[str, ...]) –The names that are configured.
Record the unknown name and the names that are configured.