feat: reusable attempt-lock primitive backed by user meta

[bordoni]

Adds a reusable primitive for bounding how often the same caller can repeat an action that costs something — a delivered message, a billed SMS, a record created upstream, or a guess at a short-lived secret — and applies it across the auth flows.

Full reference: docs/locks.md.

Why

The plugin already throttles via AuthKit\RateLimiter, a fixed-window limiter wired into every public auth route. It is cheap, it runs first, and it stays. But it is advisory by construction, for three reasons its own docblock spells out:

1. Its storage is cache, not record. Counters live in transients and an object-cache group. A flush, an eviction, or a restart of a non-persistent object cache empties them and the full allowance returns.
2. Its fallback path is not atomic. Without a persistent object cache it does a read-modify-write that concurrent requests interleave.
3. A fixed window has edges. A window opening at t permits a full allowance at t+59s and another at t+61s.

None of that matters much for smoothing a burst, which is the limiter's job. It matters when the repeated thing costs money or wears down a secret. So there are two layers now:

	RateLimiter	Attempt lock
Question	"too fast right now?"	"has this been repeated?"
Storage	transients / object cache	user meta / options
Horizon	seconds	hours
Survives a cache flush	no	yes
On repeat	identical window	escalating cooldown

The primitive

Lockable and Store contracts, with BaseLock carrying the whole engine so a concrete lock is about thirty lines — a slug and a policy.

Two counters, and the distinction is the design. strikes accumulate within a run and reset when a cooldown engages. breaches records how many times the subject has already been locked and survives the cooldown, which is what makes the ladder escalate (5 min → 15 min → 1 h → 6 h → 24 h) rather than repeat. A quiet period then forgives the subject entirely, measured from when the cooldown ends, so a short decay window can never lift a longer lock that is still holding.

Calling convention is three steps — gate, act, count:

$gate = $lock->check( $subject );
if ( is_wp_error( $gate ) ) {
    return $gate;
}

$result = do_the_expensive_thing();

$lock->record( $subject );

For anything where success is normal — a password, a code, a token — record() on failure and release() on success, so someone who mistypes their own password and then gets it right carries nothing forward.

Refusals reuse the existing workos_rate_limited / 429 / retry_after shape, so clients and the login UI need no change.

Storage

Subject	Backend
user, or an address a WP user owns	user meta, _workos_lock_{slug}
address with no WP user, IP, arbitrary key	option, workos_lock_{slug}_{sha256}, autoload off

The option fallback is the ordinary case rather than an edge case: accounts are created in WorkOS first and only mirrored into WordPress on a successful login, so plenty of real traffic references an address with no local user. A user-meta-only design would not see it at all. Subject values are hashed into keys, so no address sits in wp_options in plaintext, and a daily sweep prunes expired rows and caps the total.

When an address that already has counters gains a WordPress user, the record moves onto that user on the next read — counting stays continuous across account creation and no orphaned row is left to report a lock that no longer applies.

Locks and where they apply

Lock	Counts	Allowance	Applied in
otp_send	requests that may send a code	5 / address	magic send, password authenticate (verification refusals), signup
password_auth	failures	10 / account	password authenticate, headless ajax login, the authenticate filter
password_reset	requests that send a link	5 / account	reset start, admin-triggered reset
mfa_challenge	challenges	5 / factor	mfa challenge
signup	create attempts	3 / address	signup create
token_guess	failures	10 / token	reset confirm, signup verify, magic verify, mfa verify, invitation accept, email-change confirm/cancel

Also in scope

Two paths reached password authentication with no throttling at all, because neither goes through the REST base class:

• The anonymous admin-ajax.php headless login handler. It also relayed the upstream failure message verbatim, which distinguished between an unknown account, a wrong password and an unverified address; it now answers uniformly.
• The wp-login.php authenticate filter.

The email-change confirm and cancel routes are public by design — the emailed token is the whole credential — but nothing bounded how many tokens could be tried. Both now count failures against the presented token, hashed.

Judgement calls worth a look

• The two ledgers are kept separate. A refused sign-in sends nothing, so it must not consume the code-delivery allowance; only refusals that actually dispatch a code are counted. Counting both together meant eight wrong passwords produced a message about codes the person had never been sent — caught by a test, fixed in Password::triggered_verification_email().
• Uniform-response routes count every attempt, whether or not a send happened. Counting only real sends would make the lock engage sooner for addresses that have accounts, reintroducing the difference those routes answer uniformly to remove.
• IP subjects are deliberately weak — 4× threshold, 15-minute cooldown ceiling. Behind a CDN one address fronts an entire audience, and a durable escalating lock there would be worse than the behaviour it bounds. There is now an opt-in trusted_proxy_header setting, empty by default.
• Reset start checks the lock before its 900 ms response-time floor. A barred caller is told so outright, so there is no timing signal left to flatten, and holding a PHP worker for most of a second per rejected request works against the throttle.
• The operator surface is server-rendered. A nonced admin-post.php request gated on edit_users — not edit_user( $id ), which passes for anyone editing their own profile and would let a locked-out user lift their own lock. No REST route, no script bundle, works with JavaScript off.

Operator surfaces

"Clear login locks" on the Users list and the user-edit screen, shown only for users who hold a lock. wp workos lock list|status|clear|clear-user|gc. lock.engaged / lock.released / lock.cleared in the activity log, with subjects recorded as a kind plus a truncated hash.

Fifteen filters and two actions, each with a per-lock variant — thresholds, ladders, decay, subjects, storage and the clock are all tunable, and workos_locks_enabled turns the layer off while leaving the burst limiter in place.

Testing

633 tests, up from 570. The 63 new ones cover the engine, the three backends, the sweep, the admin gate, and the guarded flows.

The delivery test is the load-bearing one: it drives a sustained run at a single address, asserts only the allowance is forwarded, then empties the transients and the object cache and asserts the refusal holds. With the locks filtered off those assertions return 200 instead of 429, which is the point — that behaviour is exactly what the burst limiter alone cannot provide.

Full suite green, phpcs clean, phpstan level 5 clean with no baseline.

Note for reviewers: the suite must be run in two passes — --skip-group constants then --group constants — because ConfigSyncConstantsTest defines the wp-config constant overrides it exists to exercise, and those cannot be undefined for the rest of the process. CI has always split the run; composer test:wpunit now does too, and AGENTS.md documents the symptom.