Skip to content

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

InvalidSessionStrategyError(strategy: str)

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

get_strategy() -> str

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

UnknownFirewallError(name: str, configured: Sequence[str] = ())

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.