auth.login-throttle
Allow a login attempt or lock the account out, from its recent failed attempts, with the seconds until it may retry.
1.0.0 · published 2026-10-03 by charlie · Anterra
Pinned by 19 tests, run in TypeScript, Python and Rust.
What it does
Before checking a password, ask whether this account may try at all:
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 failureFor example
loginThrottle(, 1,000, max attempts 5, window seconds 900, lockout seconds 900)→ allowed true, retry after seconds 0, remaining attempts 5, locked until — no failures: every attempt remainsloginThrottle(100, 200, 300, 400, 500, max attempts 5, window seconds 900, lockout seconds 900)→ allowed true, retry after seconds 0, remaining attempts 1, locked until — four failures in the window leave one attemptloginThrottle(100, 200, 300, 400, 500, 600, max attempts 5, window seconds 900, lockout seconds 900)→ allowed false, retry after seconds 800, remaining attempts 0, locked until 1,400 the fifth failure within 15 minutes locks the account for 15 minutes from that failure
The function
The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.
export function loginThrottle(failures: readonly number[], now: number, policy: ThrottlePolicy): ThrottleDecision| failures | int[] | Unix seconds of this account's failed logins, any order; older than window plus lockout may be discarded |
| now | int | the current time in Unix seconds, read by the caller |
| policy | ThrottlePolicy | |
| returns | ThrottleDecision | allowed, or locked with retryAfterSeconds for a Retry-After header |
The types it declares, generated into your project
/** How many failures lock an account, and for how long. */
export interface ThrottlePolicy {
/** failures within the window that trigger a lockout, 1 or more */
readonly maxAttempts: number;
/** how far back failures count towards the limit, 1 or more */
readonly windowSeconds: number;
/** how long a lockout lasts, 1 or more */
readonly lockoutSeconds: number;
}
/** Whether to check the password at all, and what to tell the client. */
export interface ThrottleDecision {
readonly allowed: boolean;
/** 0 when allowed; otherwise seconds until the lockout ends */
readonly retryAfterSeconds: number;
/** failures left before a lockout; 0 while locked */
readonly remainingAttempts: number;
/** Unix seconds the lockout ends, when locked */
readonly lockedUntil: number | null;
}Your code names it in one line, in the file that uses it
import { loginThrottle } from "#fune/auth.login-throttle@^1";import { type ThrottleDecision, type ThrottlePolicy } from "./auth_login_throttle_types.ts";
function isWhole(value: unknown): value is number {
return typeof value === "number" && Number.isInteger(value);
}
/**
* Allowed or locked, by replaying the failures in time order: maxAttempts
* failures within windowSeconds of the latest lock the account for
* lockoutSeconds from that failure, and the count starts again.
*/
export function loginThrottle(failures: readonly number[], now: number, policy: ThrottlePolicy): ThrottleDecision {
if (!isWhole(policy.maxAttempts) || policy.maxAttempts < 1) throw new RangeError("maxAttempts must be a whole number of at least 1");
if (!isWhole(policy.windowSeconds) || policy.windowSeconds < 1) throw new RangeError("windowSeconds must be a whole number of at least 1");
if (!isWhole(policy.lockoutSeconds) || policy.lockoutSeconds < 1) throw new RangeError("lockoutSeconds must be a whole number of at least 1");
if (!isWhole(now)) throw new TypeError("now must be a whole number of Unix seconds");
if (!Array.isArray(failures) || !failures.every(isWhole)) throw new TypeError("failures must be whole Unix seconds");
const times = failures.filter((t) => t <= now).sort((a, b) => a - b);
let lockedUntil: number | null = null;
let streak: number[] = [];
for (const t of times) {
if (lockedUntil !== null && t < lockedUntil) continue;
streak = streak.filter((s) => s > t - policy.windowSeconds);
streak.push(t);
if (streak.length >= policy.maxAttempts) {
lockedUntil = t + policy.lockoutSeconds;
streak = [];
}
}
if (lockedUntil !== null && now < lockedUntil) {
return { allowed: false, retryAfterSeconds: lockedUntil - now, remainingAttempts: 0, lockedUntil };
}
const live = streak.filter((s) => s > now - policy.windowSeconds).length;
return { allowed: true, retryAfterSeconds: 0, remainingAttempts: policy.maxAttempts - live, lockedUntil: null };
}Install
fune buildWith that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript 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-throttleThe manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./auth.login-throttle-1.0.0-typescript.fune, or fetch it from a terminal with fune pull auth.login-throttle@1.0.0:typescript.
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.
Customise it in your app
The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.
before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.
// fune: before auth.login-throttleafter — your function gets the result and the arguments, and returns the final result.
// fune: after auth.login-throttlereplace — it requires no other capability, so there is no dependency to replace.
step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show auth.login-throttle --steps.
// fune: step auth.login-throttle after <n|label>Tests
A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.
| Case | Arguments | Expected | |
|---|---|---|---|
| no failures: every attempt remains | , 1,000, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 5, locked until — |
| four failures in the window leave one attempt | 100, 200, 300, 400, 500, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 1, locked until — |
| the fifth failure within 15 minutes locks the account for 15 minutes from that failure | 100, 200, 300, 400, 500, 600, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed false, retry after seconds 800, remaining attempts 0, locked until 1,400 |
| one second before the lockout ends | 100, 200, 300, 400, 500, 1,399, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed false, retry after seconds 1, remaining attempts 0, locked until 1,400 |
| the lockout ends exactly at lockedUntil, with the full allowance back | 100, 200, 300, 400, 500, 1,400, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 5, locked until — |
| failures given out of order are replayed in time order | 500, 300, 100, 400, 200, 600, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed false, retry after seconds 800, remaining attempts 0, locked until 1,400 |
| five failures spread over 20 minutes never have five in one window | 0, 300, 600, 900, 1,200, 1,300, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 2, locked until — |
| failures during a lockout neither count nor extend it | 100, 200, 300, 400, 500, 600, 700, 800, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed false, retry after seconds 600, remaining attempts 0, locked until 1,400 |
| after a lockout only newer failures count | 100, 200, 300, 400, 500, 1,500, 1,600, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 4, locked until — |
| a second run of five failures locks again | 100, 200, 300, 400, 500, 1,500, 1,600, 1,700, 1,800, 1,900, 2,000, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed false, retry after seconds 800, remaining attempts 0, locked until 2,800 |
Show the other 9 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| a failure stamped after now (clock skew) is ignored | 5,000, 1,000, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 5, locked until — |
| old failures fall out of the window: at 1250 only the failure at 400 is within 15 minutes | 100, 200, 300, 400, 1,250, max attempts 5, window seconds 900, lockout seconds 900 | → | allowed true, retry after seconds 0, remaining attempts 4, locked until — |
| one attempt allowed: locked by a single failure | 100, 120, max attempts 1, window seconds 60, lockout seconds 30 | → | allowed false, retry after seconds 10, remaining attempts 0, locked until 130 |
| one attempt allowed: free again after the 30-second lockout | 100, 150, max attempts 1, window seconds 60, lockout seconds 30 | → | allowed true, retry after seconds 0, remaining attempts 1, locked until — |
| zero attempts is not a policy | , 1,000, max attempts 0, window seconds 900, lockout seconds 900 | → | error: maxAttempts must be a whole number of at least 1 |
| a zero-second window | , 1,000, max attempts 5, window seconds 0, lockout seconds 900 | → | error: windowSeconds must be a whole number of at least 1 |
| a zero-second lockout | , 1,000, max attempts 5, window seconds 900, lockout seconds 0 | → | error: lockoutSeconds must be a whole number of at least 1 |
| failure times with fractions of a second | 100.5, 1,000, max attempts 5, window seconds 900, lockout seconds 900 | → | error: failures must be whole Unix seconds |
| now in fractional seconds | , 1,000.5, max attempts 5, window seconds 900, lockout seconds 900 | → | error: now must be a whole number of Unix seconds |
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
| Path | Bytes |
|---|---|
| README.md | 2,411 |
| impl/python.py | 2,059 |
| impl/rust.rs | 3,088 |
| impl/typescript.ts | 1,964 |
| vectors.json | 4,801 |