Enum AuthError 

#[non_exhaustive]
pub enum AuthError {
    InvalidToken {
        reason: String,
    },
    TokenExpired,
    InvalidSignature,
    MissingClaim {
        claim: String,
    },
    InvalidClaimValue {
        claim: String,
        reason: String,
    },
    OAuthError {
        message: String,
    },
    SessionError {
        message: String,
    },
    DatabaseError {
        message: String,
    },
    ConfigError {
        message: String,
    },
    OidcMetadataError {
        message: String,
    },
    PkceError {
        message: String,
    },
    InvalidState,
    TokenNotFound,
    SessionRevoked,
    Forbidden {
        message: String,
    },
    Internal {
        message: String,
    },
    SystemTimeError {
        message: String,
    },
    RateLimited {
        retry_after_secs: u64,
    },
    MissingNonce,
    NonceMismatch,
    MissingAuthTime,
    SessionTooOld {
        age: i64,
        max_age_secs: u64,
    },
    TokenIssuedInFuture,
    TokenTooOld,
    TokenNotYetValid,
    ForbiddenAlgorithm {
        alg: String,
    },
    InvalidCredentials,
    AccountDisabled,
    EmailAlreadyRegistered,
    InvalidRegistration {
        reason: String,
    },
}

All errors that can arise in the authentication and authorization layer.

Each variant maps to an appropriate HTTP status code via the axum::response::IntoResponse implementation in middleware.rs. Internal details are never forwarded to API clients — the IntoResponse impl always returns a generic user-facing message and logs the internal reason via tracing::warn!.

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

A supplied token could not be parsed or validated. The reason field contains internal diagnostic detail and must not be sent to API clients.

Fields

reason: String

Internal description of why the token is invalid (not forwarded to callers).

TokenExpired

The token’s exp claim is in the past.

InvalidSignature

The token’s cryptographic signature did not verify against the expected key.

MissingClaim

A required JWT claim (sub, iss, aud, etc.) was absent from the token.

Fields

claim: String

Name of the missing claim (e.g., "sub", "aud").

InvalidClaimValue

A claim was present but its value did not satisfy the validator’s constraints.

Fields

claim: String

Name of the claim that failed validation.

reason: String

Internal description of the validation failure (not forwarded to callers).

OAuthError

An error was returned by the upstream OAuth provider (e.g., during code exchange). The message field must not be forwarded to API clients — it may contain provider-internal URLs, error codes, or rate-limit state.

Fields

message: String

Provider-internal error message (not forwarded to callers).

SessionError

A session-store operation failed (creation, lookup, or revocation).

Fields

message: String

Internal session error details (not forwarded to callers).

DatabaseError

A database operation within the auth layer failed. Must never be forwarded to API clients — the message may reveal connection strings, query structure, or infrastructure topology.

Fields

message: String

Internal database error message (not forwarded to callers).

ConfigError

The auth subsystem was misconfigured or a required configuration value was missing. Must never be forwarded to API clients — the message may reveal file paths, environment variable names, or key material.

Fields

message: String

Internal configuration error details (not forwarded to callers).

OidcMetadataError

Fetching or parsing the OIDC discovery document failed.

Fields

message: String

Internal metadata fetch error details (not forwarded to callers).

PkceError

A PKCE (Proof Key for Code Exchange, RFC 7636) operation failed.

Fields

message: String

Internal PKCE error details (not forwarded to callers).

InvalidState

The OAuth state parameter did not match any stored CSRF token. This may indicate a replay attack or an expired authorization flow.

TokenNotFound

No Authorization: Bearer <token> header was present in the request.

SessionRevoked

The session associated with a refresh token has been explicitly revoked.

Forbidden

The authenticated user lacks the required permission for the requested operation. The message field contains the specific permission check detail and must not be forwarded to API clients in full (it reveals internal role/permission names).

Fields

message: String

Internal permission check details (not forwarded to callers).

Internal

An unexpected internal error occurred. Must never be forwarded to API clients.

Fields

message: String

Internal error details (not forwarded to callers).

SystemTimeError

The system clock returned an unexpected value during a time-sensitive operation. This typically indicates a misconfigured system clock or clock rollback.

Fields

message: String

Internal system time error details (not forwarded to callers).

RateLimited

The client exceeded the configured rate limit for this endpoint. Unlike most other variants, the retry window is safe to forward to clients.

Fields

retry_after_secs: u64

How many seconds the client must wait before retrying.

MissingNonce

The OIDC ID token is missing the required nonce claim.

Returned when an expected nonce was provided for comparison but the token does not carry a nonce claim. May indicate a misconfigured provider or a token replay attempt using a stripped token. See RFC 6749 §10.12 / OpenID Connect Core §3.1.3.7.

NonceMismatch

The nonce claim in the ID token does not match the expected value.

Indicates a possible token replay or session fixation attack. See RFC 6749 §10.12 / OpenID Connect Core §3.1.3.7.

MissingAuthTime

The OIDC ID token is missing the auth_time claim when max_age was requested.

When max_age is sent in the authorization request, the provider MUST include auth_time in the ID token. Its absence indicates a non-conformant provider. See OpenID Connect Core §3.1.3.7.

SessionTooOld

The session authentication time exceeds the allowed max_age.

The provider authenticated the user too long ago for this request’s max_age constraint. The user must re-authenticate to obtain a fresh session. See OpenID Connect Core §3.1.3.7.

Fields

age: i64

How many seconds ago the session was authenticated.

max_age_secs: u64

Maximum allowed authentication age in seconds (from the authorization request).

TokenIssuedInFuture

The token’s iat (issued-at) claim is more than crate::jwt::MAX_CLOCK_SKEW_SECS seconds in the future.

A token with a future iat was either issued by a clock-skewed provider or forged. RFC 7519 §4.1.6 defines iat as the time the JWT was issued; values substantially ahead of the current time are not credible.

TokenTooOld

The token’s iat (issued-at) claim is more than crate::jwt::MAX_TOKEN_AGE_SECS seconds in the past.

Excessively old tokens may be replayed credentials. Short-lived access tokens expire via exp long before this limit is reached; this guard targets long-lived or replayed tokens. Re-authenticate to obtain a fresh token.

TokenNotYetValid

The current time is before the token’s nbf (not-before) claim.

RFC 7519 §4.1.5 prohibits accepting tokens before the nbf time (plus the allowed clock-skew tolerance). This typically indicates a race condition, a misconfigured issuer, or a replayed token from a future session.

ForbiddenAlgorithm

The OIDC ID token uses a signing algorithm that is explicitly forbidden.

Symmetric algorithms (HS256, HS384, HS512) are forbidden on the OIDC path because OIDC providers MUST use asymmetric keys (RS256, RS384, RS512, ES256, ES384). A token claiming a symmetric algorithm was either issued by a misconfigured provider or crafted by an attacker attempting an algorithm substitution attack (RFC 8725 §2.1).

The alg field carries the forbidden algorithm name for operator logging; it MUST NOT be forwarded to API clients.

Fields

alg: String

The algorithm name from the JWT header (e.g., "HS256").

InvalidCredentials

A local email + password login failed because the user is unknown or the password was wrong.

These two cases are deliberately merged into a single variant so the client cannot distinguish them (no user-existence oracle); the precise reason is recorded in the server audit log instead. The login path equalizes timing across both cases by always performing an Argon2 verification.

AccountDisabled

A local email + password login presented the correct password for an account whose local sign-in has been administratively disabled.

Only reachable after a successful password verification, so it never reveals account state to a party that does not already hold valid credentials.

EmailAlreadyRegistered

A local signup was attempted for an email that already has a local credential.

InvalidRegistration

A local signup was rejected by input validation (malformed email or a password that violates the length policy).

The reason carries the specific validation detail for server-side logging; the IntoResponse impl returns a generic message to the client.

Fields

reason: String

Internal validation detail (not forwarded to callers).

Trait Implementations

impl Clone for AuthError

fn clone(&self) -> AuthError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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 FraiseQLError

Lossless composition into the canonical fraiseql_error::FraiseQLError.

The auth subsystem owns this conversion (sqlx pattern) so that fraiseql-error can stay a leaf crate in the workspace dependency graph. The boxed payload preserves the full AuthError vocabulary via the Display/source chain.

fn from(e: AuthError) -> Self

Converts to this type from the input type.

impl IntoResponse for AuthError

fn into_response(self) -> Response

Create a response.