xtr_security_jwt.exception ¶
The errors this library raises, one family under one base.
The signing and verification failures derive from :class:JwtFailureError
(itself a :class:~xtr_security_core.exception.SecurityError); the errors the
authenticator raises for a request derive from the family's
:class:~xtr_security_core.exception.AuthenticationError. One
except SecurityError still catches every one of them.
ExpiredTokenError ¶
ExpiredTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A caller presented a token whose expiry has passed.
Drawn from the family's :class:~xtr_security_core.exception.AuthenticationError
so the firewall turns it into a challenge; its public message names the
expiry rather than leaking why the token was refused.
InvalidPayloadError ¶
Bases: AuthenticationError
A verified token carried no claim naming the user it stands for.
The signature checked, but the claim the manager reads the user's
identifier from — the configured user-id claim — was absent, so the token
proves nobody. Drawn from
:class:~xtr_security_core.exception.AuthenticationError.
Attributes:
-
invalid_key(str) –The claim the payload was expected to carry.
Record the invalid_key the payload did not carry.
InvalidTokenError ¶
InvalidTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A caller presented a token that is malformed, unsigned or tampered with.
The catch-all for a token the verifier refused for any reason other than
expiry: a bad signature, a disallowed algorithm, a structural fault. Drawn
from :class:~xtr_security_core.exception.AuthenticationError.
JwtDecodeFailureError ¶
Bases: JwtFailureError
Reading a token back into claims failed.
Its reason tells the three apart: :data:INVALID_TOKEN for a token that
could not be read or whose issued-at time is in the future,
:data:EXPIRED_TOKEN for one past its expiry, and :data:UNVERIFIED_TOKEN
for one whose signature does not verify against any known key.
JwtEncodeFailureError ¶
Bases: JwtFailureError
Signing a set of claims into a token failed.
Its reason is :data:INVALID_CONFIG when the signing key or algorithm
the provider was built with cannot produce a signature, or
:data:UNSIGNED_TOKEN when the provider returned a token it did not sign.
JwtFailureError ¶
Bases: SecurityError
A token could not be signed or verified, carrying a machine reason.
The base of the encode and decode failures. It carries a reason — one
of the reason constants its subclasses declare — and, when a token was read
far enough to have one, the payload that was decoded. Deriving from the
family's :class:~xtr_security_core.exception.SecurityError keeps one
except SecurityError catching every error the family raises.
Attributes:
-
reason(str) –The machine-readable cause, a subclass reason constant.
-
payload(dict[str, object] | None) –The claims decoded before the failure, when there were any.
Record the reason and the payload decoded before failing.
MissingKeyError ¶
Bases: InvalidArgumentError
No signing or verifying key is configured, or the key file it names is not there.
The bundle builds and boots without a key, so the console stays usable to
mint one; the absence is reported here, the first time a token is signed or
verified. It is a deployment's mistake, never a client's: the encoder lets it
through rather than reporting it as a token that failed to verify, so a
request meeting it fails as a server error instead of a 401.
Attributes:
-
location(str | None) –The key file that was looked for, or
Nonewhen no key is configured at all.
Record the key file looked for, or that no key is configured at all.
MissingTokenError ¶
MissingTokenError(message: str | None = None, *, message_key: str | None = None, message_data: Mapping[str, object] | None = None)
Bases: AuthenticationError
A request reached a protected resource carrying no token at all.
Raised by the authenticator's entry point when a firewall needs authentication and no extractor found a token, so the challenge names that the token was missing rather than wrong.