auth.login-throttle

decision = loginThrottle(recentFailures, now, {maxAttempts: 5, windowSeconds: 900, lockoutSeconds: 900})
if not allowed: answer 429 with Retry-After: retryAfterSeconds (and do not check the password)
else: check it; on failure, record `now` as another failure

def login_throttle(failures: Sequence[int], now: int, policy: ThrottlePolicy) -> ThrottleDecision

@dataclass(frozen=True)
class ThrottlePolicy:
    """How many failures lock an account, and for how long."""

    #: failures within the window that trigger a lockout, 1 or more
    max_attempts: int
    #: how far back failures count towards the limit, 1 or more
    window_seconds: int
    #: how long a lockout lasts, 1 or more
    lockout_seconds: int

@dataclass(frozen=True)
class ThrottleDecision:
    """Whether to check the password at all, and what to tell the client."""

    allowed: bool
    #: 0 when allowed; otherwise seconds until the lockout ends
    retry_after_seconds: int
    #: failures left before a lockout; 0 while locked
    remaining_attempts: int
    #: Unix seconds the lockout ends, when locked
    locked_until: Optional[int]

from fune.auth.login_throttle import login_throttle  # auth.login-throttle@^1

from typing import Any, List, Optional, Sequence

from .auth_login_throttle_types import ThrottleDecision, ThrottlePolicy


def _is_whole(value: Any) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def login_throttle(failures: Sequence[int], now: int, policy: ThrottlePolicy) -> ThrottleDecision:
    """Allowed or locked, by replaying the failures in time order: max_attempts
    failures within window_seconds of the latest lock the account for
    lockout_seconds from that failure, and the count starts again."""
    if not _is_whole(policy.max_attempts) or policy.max_attempts < 1:
        raise ValueError("maxAttempts must be a whole number of at least 1")
    if not _is_whole(policy.window_seconds) or policy.window_seconds < 1:
        raise ValueError("windowSeconds must be a whole number of at least 1")
    if not _is_whole(policy.lockout_seconds) or policy.lockout_seconds < 1:
        raise ValueError("lockoutSeconds must be a whole number of at least 1")
    if not _is_whole(now):
        raise TypeError("now must be a whole number of Unix seconds")
    if isinstance(failures, (str, dict)) or not all(_is_whole(t) for t in failures):
        raise TypeError("failures must be whole Unix seconds")

    locked_until: Optional[int] = None
    streak: List[int] = []
    for t in sorted(t for t in failures if t <= now):
        if locked_until is not None and t < locked_until:
            continue
        streak = [s for s in streak if s > t - policy.window_seconds]
        streak.append(t)
        if len(streak) >= policy.max_attempts:
            locked_until = t + policy.lockout_seconds
            streak = []
    if locked_until is not None and now < locked_until:
        return ThrottleDecision(allowed=False, retry_after_seconds=locked_until - now, remaining_attempts=0, locked_until=locked_until)
    live = sum(1 for s in streak if s > now - policy.window_seconds)
    return ThrottleDecision(allowed=True, retry_after_seconds=0, remaining_attempts=policy.max_attempts - live, locked_until=None)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add auth.login-throttle

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./auth.login-throttle-1.0.0-python.fune, or fetch it from a terminal with fune pull auth.login-throttle@1.0.0:python.

The whole function, every language, is one file too: auth.login-throttle-1.0.0.fune, 18,062 bytes, sha256 cb6d13f80567a633f50be0eb2ba9f2432ad3e1c6d9138f5a2bbae76f7cc2d544. It installs into a project of any language.

# fune: before auth.login-throttle

# fune: after auth.login-throttle

# fune: step auth.login-throttle after <n|label>

More from the author

The application stores the times of failed logins per account (per normalised email, so an attacker cannot dodge the count by changing case) and passes them in with the current time. The capability keeps no state and reads no clock.

**The rule.** Failures are replayed in time order. When `maxAttempts` failures fall within `windowSeconds` of each other (each within the window ending at the latest), the account is locked from that failure for `lockoutSeconds`, and the count starts again from zero. Failures recorded while locked do not count and do not extend the lockout (the application should not be recording them, since it does not check the password then). A lockout ends exactly at `lockedUntil`: at that second the account is allowed again, with its full allowance, because the failures that caused the lockout have been paid for. Failures stamped after `now` (clock skew between servers) are ignored.

`remainingAttempts` is how many more failures the account can have before it is locked, counting only failures still inside the window; a login form may show it ("2 attempts left"), though many sites prefer not to.

**Settings.** 5 attempts in 15 minutes and a 15-minute lockout (`{5, 900, 900}`) is a common, humane default: it stops online guessing (at most 480 guesses a day) while a forgetful person is inconvenienced for minutes, not locked out until support replies. NIST SP 800-63B-4 section 3.2.2 requires limiting consecutive failed attempts to no more than 100, so any setting here meets that; OWASP's Authentication Cheat Sheet discusses the trade-off with denial of service against known usernames.

A successful login does not clear earlier failures here; if the application wants that, it deletes the stored failures on success.

Sources: NIST SP 800-63B-4, section 3.2.2, Rate Limiting (Throttling) (https://pages.nist.gov/800-63-4/sp800-63b.html); OWASP Authentication Cheat Sheet, Account Lockout (https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html); RFC 9110 section 10.2.3, Retry-After.

Files