Enum AuthState 

pub enum AuthState {
    Guest,
    Identifying {
        user_id: UserId,
        tenant_id: TenantId,
    },
    Authenticating {
        user_id: UserId,
        tenant_id: TenantId,
        method_name: Arc<str>,
        remaining: Vec<FactorKind>,
        completed: Vec<FactorKind>,
        attempt_count: u32,
        last_attempt: Option<DateTime<Utc>>,
    },
    Authenticated {
        user_id: UserId,
        tenant_id: TenantId,
        authn_time: DateTime<Utc>,
        factors_completed: Vec<FactorKind>,
    },
    PendingWorkflow {
        user_id: UserId,
        tenant_id: TenantId,
        workflow: WorkflowState,
    },
}

Authentication state machine: flat enum, typed UserId / TenantId IDs.

The state machine follows a strict forward progression with PendingWorkflow as a post-authentication holding state.

State transition diagram

                    ┌───────────────────────────┐
                    │ (app-level, optional)      │
 Guest ─┬──────────►│ Identifying ──► Authenticating ──► Authenticated
        │           └───────────────────────────┘          ▲
        │                                                  │
        └──► Authenticating ──► Authenticated              │
        │         (begin_login default path)               │
        │                                                  │
        └──► PendingWorkflow(Signup) ──────────────────────┘
   ▲              (begin_signup)           (complete_signup)
   │                                                       │
   │              (logout / session clear)                  │
   └───────────────────────────────────────────────────────-┘

• Guest: anonymous visitor, no authentication started.
• Identifying: optional state for username-first flows. The built-in AuthnService::begin_login() skips this and goes directly to Authenticating. Available via session.set_identifying() for apps that need a two-step identify-then-authenticate UX.
• Authenticating: progressing through a multi-factor method; remaining tracks which factor kinds are still to be verified.
• Authenticated: all required factors verified; full access granted.
• PendingWorkflow: blocked on a post-auth step (signup, KYC, password reset, etc.). Reached via begin_signup() or app-level workflow initiation.

Calling AuthSession::clear from any state resets the session back to Guest (logout).

Variants

Guest

No authentication started; anonymous visitor.

Identifying

User identified (username entered), first factor not yet verified.

Fields

user_id: UserId

Identifier of the user being authenticated.

tenant_id: TenantId

Tenant the user belongs to.

Authenticating

Progressing through a multi-factor method.

Fields

user_id: UserId

Identifier of the user being authenticated.

tenant_id: TenantId

Tenant the user belongs to.

method_name: Arc<str>

Human-readable method name, e.g. "password+totp".

remaining: Vec<FactorKind>

Ordered list of factor kinds still to be verified.

completed: Vec<FactorKind>

Factor kinds that have already been verified in this flow, in the order they were completed. Carried into AuthState::Authenticated::factors_completed on transition so audit events can record the full list.

attempt_count: u32

Number of failed attempts on the current factor step.

last_attempt: Option<DateTime<Utc>>

Timestamp of last attempt (for rate limiting / lockout).

Authenticated

All factors verified: user is fully authenticated.

Fields

user_id: UserId

Identifier of the authenticated user.

tenant_id: TenantId

Tenant the user belongs to.

authn_time: DateTime<Utc>

Wall-clock time when authentication completed (from injectable Clock).

factors_completed: Vec<FactorKind>

Factor kinds that were verified to reach this state, in completion order. Used by the audit log to distinguish “user logged in with password only because the tenant disables TOTP” (legitimate single-factor) from “user reached Authenticated without verifying TOTP” (bypass attack). Empty for sessions whose state predates this field; serde(default) keeps existing serialized sessions readable.

PendingWorkflow

Authenticated but blocked on a post-auth workflow (e.g. signup, KYC, password reset).

Fields

user_id: UserId

Identifier of the user awaiting workflow completion.

tenant_id: TenantId

Tenant the user belongs to.

workflow: WorkflowState

Workflow currently blocking full authentication (e.g. signup, KYC).

Implementations

impl AuthState

pub fn user_id(&self) -> Option<&UserId>

Return the authenticated user ID if one is associated with this state.

pub fn tenant_id(&self) -> Option<&TenantId>

Return the tenant ID if one is associated with this state.

pub fn is_authenticated(&self) -> bool

Return true if this state represents a fully authenticated session.

pub fn is_guest(&self) -> bool

Return true if this is an unauthenticated guest session.

pub fn is_authenticating(&self) -> bool

Return true if the session is in progress through a multi-factor flow.

Use this to guard MFA factor-verification routes.

Trait Implementations

impl Clone for AuthState

fn clone(&self) -> AuthState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AuthState

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

Formats the value using the given formatter.

impl Default for AuthState

fn default() -> AuthState

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AuthState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for AuthState

fn eq(&self, other: &AuthState) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for AuthState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for AuthState