Struct Guard 

pub struct Guard<St, S = Uuid> { /* private fields */ }

Issues, checks, rotates and revokes sessions. Cheap to clone; clones share state.

St is the SessionStore; S is your subject type (default Uuid), stored opaquely.

Implementations

impl<St: SessionStore, S: Subject> Guard<St, S>

pub fn layer(&self) -> GuardLayer<St, S>

Available on crate feature axum only.

A tower layer that authenticates every request through this guard.

See GuardLayer for what it does per request and how to configure it.

use std::{net::SocketAddr, time::Duration};

use axum::{Router, http::HeaderMap, routing::post};
use session_guard::{AuthSession, Checks, Guard, MemoryStore};
use uuid::Uuid;

async fn transfer(session: AuthSession<Uuid>) -> &'static str {
    "done"
}

let guard = Guard::new(MemoryStore::new());
let layer = guard
    .layer()
    .with(Checks::strict())
    .require_recent_auth(Duration::from_mins(15))
    .bypass_bearer_prefixes(["pat_", "svc_"])
    .bypass_when(|headers: &HeaderMap| headers.contains_key("x-internal-probe"));
let app = Router::new().route("/transfer", post(transfer)).layer(layer);

let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
axum::serve(listener, app.into_make_service_with_connect_info::<SocketAddr>()).await

impl<St: SessionStore> Guard<St>

pub fn new(store: St) -> Self

A guard with the default configuration and Uuid subjects.

pub fn builder(store: St, config: GuardConfig) -> GuardBuilder<St>

Starts building a guard. Subjects are Uuid unless changed with GuardBuilder::subject.

impl<St: SessionStore, S: Subject> Guard<St, S>

pub async fn login( &self, subject: &S, ctx: &ClientContext, previous_token: Option<&str>, ) -> Result<NewSession, GuardError>

Creates a session for subject and returns its first token.

Pass the token the client presented, if any: that session is revoked first, so a token planted before login (session fixation) never becomes authenticated. Call this only after verifying the subject’s credentials, and rate-limit that endpoint yourself.

Errors

Store failures, an unavailable RNG, or a subject that does not serialize.

pub async fn authenticate( &self, token: &str, ctx: &ClientContext, ) -> Result<Outcome<S>, GuardError>

Checks a request’s token with the configured checks.

On success the request may proceed; send Authenticated::rotated back as Set-Cookie when present. Every Rejection maps to 401.

Errors

Store failures only. Bad tokens and risky clients are Outcome::Rejected.

pub async fn authenticate_with( &self, token: &str, ctx: &ClientContext, checks: &Checks, ) -> Result<Outcome<S>, GuardError>

Like authenticate with other checks, for routes that need stricter (or looser) treatment. The baseline learns only the signals checks scored.

Errors

Store failures only.

pub async fn peek( &self, token: &str, ) -> Result<Option<SessionInfo<S>>, GuardError>

Looks a token up without changing anything: no rotation, no last_seen write, no checks. None unless the token is current (or within its grace period) and the session is live.

Errors

Store failures only.

pub async fn complete_step_up( &self, token: &str, ctx: &ClientContext, verified_subject: &S, ) -> Result<StepUpOutcome, GuardError>

Clears a pending step-up after the app has re-verified the subject (password, passkey, OTP…). The current client becomes the new baseline, authenticated_at resets and a new token is issued.

verified_subject must be the subject the app just verified; a mismatch changes nothing. Rate-limit the verification yourself.

Errors

Store failures or an unavailable RNG.

pub async fn logout( &self, token: &str, ctx: &ClientContext, ) -> Result<bool, GuardError>

Ends the session the token belongs to. Returns whether there was one.

Errors

Store failures only.

pub async fn revoke_session( &self, subject: &S, session_id: Uuid, ctx: &ClientContext, ) -> Result<bool, GuardError>

Deletes one session of subject by id, e.g. from a “your devices” page. Returns whether it existed; a session of another subject is left alone. ctx is whoever asked; it goes into the EventKind::Revoked event.

Errors

Store failures or a subject that does not serialize.

pub async fn revoke_all_for_subject( &self, subject: &S, ctx: &ClientContext, ) -> Result<u64, GuardError>

Deletes every session of subject, e.g. after a password change. Returns how many. ctx is whoever asked; each session gets an EventKind::Revoked event.

Errors

Store failures or a subject that does not serialize.

pub async fn list_sessions( &self, subject: &S, ) -> Result<Vec<SessionInfo<S>>, GuardError>

The live sessions of subject.

Errors

Store failures or a subject that does not serialize.

pub async fn purge_expired(&self) -> Result<PurgeReport, GuardError>

Deletes expired sessions and events older than the retention period. Run it periodically (hourly is plenty).

Errors

Store failures only.

pub fn spawn_purge(&self, every: Duration) -> JoinHandle<()>

Available on crate feature tokio only.

Runs purge_expired now and then every every on the tokio runtime, logging each report (info) or failure (warn) with tracing. A failed run does not stop the task; abort the handle to stop it.

Panics

Outside a tokio runtime, or if every is zero.

pub fn client_context<H: HeaderSource + ?Sized>( &self, peer: IpAddr, headers: &H, ) -> ClientContext

Builds the ClientContext for a request from the TCP peer address and the request headers.

X-Forwarded-For is honoured only when peer is a configured trusted proxy, walking right to left past trusted hops. Header values are capped at the configured length.

pub fn cookie_token<'a, H: HeaderSource + ?Sized>( &self, headers: &'a H, ) -> Option<&'a str>

The session cookie’s value from the request’s Cookie headers, if present.

pub fn clear_cookie(&self) -> String

A Set-Cookie value that deletes the session cookie.

pub fn requires_reauth( &self, session: &AuthSession<S>, max_age: Duration, ) -> bool

Whether the subject last proved who they are more than max_age ago. Use it to demand a fresh login before sensitive actions.

With a zero max_age it is true as soon as any time has passed since the login or step-up, so it is true for practically every request.

pub fn is_session_token(&self, value: &str) -> bool

Whether value has the shape of this guard’s tokens (configured prefix, then 43 base64url characters). Does not touch the store.

Trait Implementations

impl<St, S> Clone for Guard<St, S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<St, S> Debug for Guard<St, S>

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

Formats the value using the given formatter.