Enum AuthError 

pub enum AuthError {
    Forbidden,
    DidMethodRejected,
    PendingChallengeLimitReached,
    SessionNotFound,
    SessionStateMismatch,
    ChallengeMismatch,
    ChallengeExpired,
    SignerMismatch,
    StaleMessage,
    RefreshTokenInvalid,
    RefreshTokenExpired,
    AttestationFailed(String),
    Internal(String),
}

Auth-specific failures the canonical handlers can raise.

Each backend’s Error associated type must implement From<AuthError> so the handler can return these variants and the route layer surfaces them via its existing IntoResponse plumbing (e.g. vti-common’s AppError::Unauthorized(_) arm).

Variants

Forbidden

DID is not in the backend’s ACL, or the ACL entry is expired. Returned as 403 Forbidden to avoid revealing whether the DID exists in the ACL system at all (timing-side-channel mitigation; the ACL check happens before any other gate).

DidMethodRejected

The DID’s method (e.g. did:foo:...) is not in the backend’s allowlist. Distinct from Forbidden so audit logs can distinguish “wrong method” from “not in ACL”. Surfaced to callers as a generic 403 to avoid leaking the allowlist contents.

PendingChallengeLimitReached

Too many concurrent ChallengeSent sessions for this DID; the per-DID rate limit (default 10) is exhausted. Returned as 429 Too Many Requests so clients can back off.

SessionNotFound

The session referenced by the request does not exist or has expired (TTL swept it). Returned as 401 Unauthorized; the holder must restart the challenge flow.

SessionStateMismatch

The session exists but was already authenticated (replay) or is otherwise not in the state the request expected. Returned as 401 Unauthorized; the holder must restart.

ChallengeMismatch

The presented challenge does not match what was issued for this session. Constant-time compared. Returned as 401 Unauthorized.

ChallengeExpired

The challenge is older than the backend’s configured TTL. Returned as 401 Unauthorized; the holder must request a fresh challenge.

SignerMismatch

The signer DID extracted from the transport (DIDComm from, SIOPv2 iss) does not match the DID the session was issued to. Critical binding — without this check, any leaked challenge could be redeemed by any signer. Returned as 401 Unauthorized.

StaleMessage

The DIDComm envelope’s created_time is outside the freshness window. Replay defense for the DIDComm transport. Returned as 401 Unauthorized.

RefreshTokenInvalid

The refresh token was not found or already consumed. Atomic claim semantics: at most one caller succeeds per token. Returned as 401 Unauthorized; the holder must re-authenticate.

RefreshTokenExpired

The refresh token’s absolute expiry has passed. Returned as 401 Unauthorized; the holder must re-authenticate.

AttestationFailed(String)

TEE attestation failed in a TeeMode::Required deployment. Returned as 503 Service Unavailable (the operator’s TEE is broken; the caller did nothing wrong).

Internal(String)

Surface for any wrapped error from the backend’s policy or storage layer that doesn’t fit the variants above. The canonical handler does not introspect this; it surfaces unchanged via the backend’s Error::from(AuthError::Internal).

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 AppError

Convert the canonical auth-flow errors into AppError so the route layer’s existing IntoResponse plumbing renders them without backend-specific glue. Each variant lands on the HTTP status reflected in the crate::auth::AuthError doc-comments:

• Forbidden, DidMethodRejected → 403
• PendingChallengeLimitReached → 429 via the Validation arm (route layer can return a typed 429 if needed; the canonical variant carries the rate-limit signal in the message).
• SessionNotFound, SessionStateMismatch, ChallengeMismatch, ChallengeExpired, SignerMismatch, StaleMessage, RefreshTokenInvalid, RefreshTokenExpired → 401
• AttestationFailed → 503 via Internal (TEE outages are not the caller’s fault).
• Internal → 500.

fn from(e: AuthError) -> Self

Converts to this type from the input type.