shoc-backend/SeaHaven.Services/Interfaces/IPasswordResetThrottle.cs

namespace SeaHaven.Services.Interfaces
{
    /// <summary>
    /// Per-account limits on the anonymous password reset flow, keyed on the
    /// normalized email so they hold however many client addresses an attacker uses.
    /// </summary>
    public interface IPasswordResetThrottle
    {
        /// <summary>
        /// Counts a code request for the email and returns true while it is within the
        /// hourly and daily limits. A refused request is not counted.
        /// </summary>
        bool TryAcceptCodeRequest(string email);

        /// <summary>
        /// Reserves one failed check for the email before a code is compared. Returns
        /// false once the account has used its failed checks for the window.
        /// </summary>
        bool TryReserveCheck(string email);

        /// <summary>Gives back the reservation of a check whose code matched.</summary>
        void ReleaseCheck(string email);
    }
}