Enum AuthError 

#[non_exhaustive]
pub enum AuthError {
    InvalidToken,
    ExpiredSession,
    MissingAuth,
    Denied {
        reason: String,
    },
    Provider(Box<dyn Error + Send + Sync + 'static>),
}

Authentication and authorization failure modes. Returned by DjogiAuth::authenticate and DjogiAuth::verify, and re-raised as DjogiError::Auth when those calls propagate through ? inside framework operations.

Matching

The enum is #[non_exhaustive]. All downstream match arms must end with a wildcard:

match err {
    AuthError::InvalidToken => { /* ... */ }
    AuthError::ExpiredSession => { /* ... */ }
    _ => { /* forward-compatible catch-all */ }
}

Error hierarchy

AuthError is narrowly scoped to authentication and authorization logic. It does NOT carry database/driver errors (those flow through DjogiError::Db). Use AuthError::Provider to wrap any provider-internal failure that is not covered by a more specific variant.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

InvalidToken

The token did not parse or did not resolve to a known session or user. Returned when the opaque bearer token passed to DjogiAuth::authenticate is malformed, has an invalid signature, or does not correspond to any session the provider can resolve.

ExpiredSession

A previously-valid session has expired. Distinct from InvalidToken so callers can give users a more specific prompt (“please log in again”) rather than treating expiry as a completely unknown error.

MissingAuth

An auth-required operation was attempted without an attached AuthContext on the DjogiContext. Raised by framework guard helpers when a route or model method that requires authentication is invoked against a context that has no auth attached via DjogiContext::with_auth.

Denied

DjogiAuth::verify returned a denial. reason is an implementation-supplied explanation suitable for logging — it is NOT necessarily safe to forward to end users.

When to use

Return this variant when the resolved AuthContext is valid (the user is authenticated) but the specific action they attempted is not permitted (the user is not authorized). This keeps the “who are you” and “can you do this” failure paths distinguishable by callers.

Fields

reason: String

Human-readable explanation of why the action was denied. Suitable for structured logging. Not guaranteed safe for end-user display — scrub before including in HTTP responses.

Provider(Box<dyn Error + Send + Sync + 'static>)

Provider-internal error (JWT parse failure, HTTP fetch to an OIDC issuer, key-store lookup, etc.). Wraps any Error + Send + Sync + 'static so every provider can surface its own error hierarchy without this enum growing per-provider variants.

When to use

Use this variant for failures that originate inside the provider implementation and do not map to a more specific AuthError variant. Database/driver errors that bubble up from a Postgres lookup should be converted to DjogiError::Db at the boundary instead — they do not belong here.

Trait Implementations

impl Debug for AuthError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for AuthError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for AuthError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<AuthError> for DjogiError

fn from(source: AuthError) -> Self

Converts to this type from the input type.