Shipmind Labs

A tester sat on our OTP endpoint for a whole afternoon and never got blocked for longer than the cooldown we had configured.

The lockout fired exactly as designed. Too many wrong codes, locked until a timestamp. Wait it out, try again. What we missed is that "try again" also meant "start over": the failure tally reset to zero along with the lock, so every round began from a clean record. Fixed cooldown, fixed batch of guesses, repeat. We had built a rate limiter and called it a lockout.

The fix was to split one counter into two.

In otpguard, our open-source OTP library, the whole lockout state sits in one record: the failure tally, the locked-until timestamp, and a separate lock count. When the lock expires we rebuild the record from scratch, but we carry the lock count forward. The tally restarts at zero, the strikes survive. The second lockout runs longer than the first, the third longer than the second.

Three things we learned wiring that up.

An escalating policy has to name its ceiling. Our policy object refuses to be constructed with escalation above 1 and no maximum duration. Otherwise an exponent eventually produces a lock nobody intended, and you find that out in production. It also refuses a maximum shorter than the base duration, a config typo we would rather catch at startup than during an incident.

Exponents need a guard, not a try/except. Before computing the base duration times escalation to the power of the lock count, we compare the logarithms of both sides. If the exponent would pass the cap, we return the cap. A corrupted or absurd stored count gives you the maximum lock instead of an overflow.

The record has to outlive the lock it carries. We store the failed record for the lock duration plus the code lifetime. Expire it on the lock boundary and the strike count vanishes at the exact moment it becomes useful, which is how the original bug felt from the outside: state that looked persistent and wasn't.

One migration detail that saved us a backfill: the lock count is omitted from the serialized form while it is zero, and a missing field decodes as zero. Records written before the field existed still load.

If you run lockouts in production, go and check whether your penalty counter survives the reset of the thing it counts. That is the whole difference between slowing an attacker down and stopping one.

Was this useful?

Building something similar?

or email hello@shipmindlabs.com