pub struct AuthGuard { /* private fields */ }Expand description
Sharded in-process tracker of failed auth attempts plus lockout
state, keyed by (IpAddr, username) and by IpAddr alone.
Both counters slide over time windows configured in
AuthGuardConfig. The IP-only counter applies regardless of
which username was attempted, so a single attacker spraying many
usernames eventually hits the IP-level lockout.
Implementations§
Source§impl AuthGuard
impl AuthGuard
Sourcepub fn new(config: AuthGuardConfig) -> Self
pub fn new(config: AuthGuardConfig) -> Self
Construct a guard with the given thresholds. Use
AuthGuardConfig::default() for the SMTP/IMAP-tuned defaults.
Sourcepub fn check(&self, ip: IpAddr, username: &str) -> AuthCheck
pub fn check(&self, ip: IpAddr, username: &str) -> AuthCheck
Check whether (ip, username) is currently in lockout.
Read-only; does not record an attempt. Call before doing
the actual password verification. If Allowed, do the verify;
if LockedOut, reject without touching the password backend.
The check looks at both the per-IP and per-(IP, username) counters and returns the first matching lockout. IPv6 addresses are normalized to their /64 prefix.
Sourcepub fn record_failure(&self, ip: IpAddr, username: &str)
pub fn record_failure(&self, ip: IpAddr, username: &str)
Record a failed auth attempt. Call when the password verify returns “wrong credentials” — including the case where the account doesn’t exist (constant-time policy).
Increments both the per-IP and per-(IP, username) counters. May tip one or both over their threshold and arm a lockout.
Sourcepub fn record_success(&self, ip: IpAddr, username: &str)
pub fn record_success(&self, ip: IpAddr, username: &str)
Record a successful auth. Clears the per-(IP, username) counter (so a legitimate user who fat-fingered then succeeded doesn’t accumulate against future attempts).
Does not clear the per-IP counter, because a successful auth from one user doesn’t prove the IP isn’t being abused against another. Use cleanup_stale + time decay for that.
Sourcepub fn cleanup_stale(&self, before: Instant)
pub fn cleanup_stale(&self, before: Instant)
Drop records whose lockouts have already expired before
before. Call periodically (every few minutes) from a
background task to keep the maps bounded under sustained
attack volume.
Records with active lockouts or recent in-window failures are preserved.