AshAuthentication.AddOn.AuditLog.BruteForceHelpers (ash_authentication v5.0.0-rc.6)

Copy Markdown View Source

Helpers for audit log-based brute force protection.

Provides shared functionality for counting failed authentication attempts from the audit log. Used by the TOTP, recovery code, password and magic link strategies when configured with brute_force_strategy {:audit_log, :audit_log}.

Summary

Types

criteria()

Functions

count_failures(audit_log, criteria, cutoff)

Counts failed attempts matching the given criteria within a time window.

count_failures(audit_log, subject, strategy_name, cutoff)

Counts failed attempts for a subject and strategy within a time window.

Types

criteria()

@type criteria() :: [subject: String.t(), identity: String.t(), strategy: atom()]

Functions

count_failures(audit_log, criteria, cutoff)

@spec count_failures(struct(), criteria(), DateTime.t()) ::
  {:ok, non_neg_integer()} | {:error, any()}

Counts failed attempts matching the given criteria within a time window.

criteria is a keyword list that may contain any of:

  • :subject - the user's authentication subject
  • :identity - the submitted identity (e.g. email or username)
  • :strategy - the strategy name

The audit log entries must additionally have status == :failure and have been logged_at at or after the given cutoff.

Uses a FOR UPDATE lock to prevent race conditions where multiple concurrent requests could slip past the brute force limit.

Returns {:ok, count} or {:error, reason}.

count_failures(audit_log, subject, strategy_name, cutoff)

@spec count_failures(struct(), String.t(), atom(), DateTime.t()) ::
  {:ok, non_neg_integer()} | {:error, any()}

Counts failed attempts for a subject and strategy within a time window.

See count_failures/3 for the more general form.