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>Gives back an accepted code request whose email could not be queued.</summary>
        void ReleaseCodeRequest(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 a reservation that did not become a failed guess: the code matched,
        /// or there was no live code to compare it with.
        /// </summary>
        void ReleaseCheck(string email);
    }
}