feat: throttle + lock step-up confirmation, and seven audit fixes

[stsepelin]

Closes the largest remaining §5.2.2 hole, then folds in the findings of a full white-box audit run against the 0.5.0 release candidate.

1. Step-up confirmation was unthrottled

POST /auth/confirm-password and /auth/confirm-passkey had no rate limit at all — only the guard. Password confirmation re-verifies the same secret the login route throttles two ways and can now lock, so anyone already holding an access token had an unmetered password oracle behind the sudo gate.

Both routes now run lukk-confirm (rate_limits.confirm, 5/60s) keyed on the user and the IP — the per-user bucket is load-bearing, since a stolen token is one identity behind any number of addresses. The extra guards get lukk-{guard}-confirm with the same per-user bucket. With features.lockout on, failures count toward the §5.2.2 cap under a new confirm purpose; a successful login or a password reset clears it. confirm-passkey is metered but not locked — an assertion is a signature, not a guessable secret.

2. Seven audit fixes

Three parallel white-box passes (auth/rate-limiting/lockout, token crypto/rotation/revocation, optional features/data-at-rest), each asked to prove findings by reproducing them. Each fix is pinned by a regression test.

ID	Sev
SUBJ-1	High	An attacker could clear a victim's lockout at will. The subject was transliterate(lower(trim(...))) — many-to-one across real accounts (аdmin@ with a Cyrillic а; ADMIN@ on binary-collation engines). Two accounts shared one counter, and a password reset releases on that subject, so whoever controlled a look-alike could lock the victim, reset their own password, clear the lock, repeat. Now keyed on id:<pk>, falling back to idn:<normalized> so an identifier naming no account still counts — otherwise 423-vs-422 is an existence oracle.
GUARD-1	Medium	Step-up bypass under multi-guard. lukk.confirm resolved its verifier from lukk.set-guard, which never runs on a consumer's own route — so an admin route verified against the users guard's key and audience. Reproduced: 200 where 423 was required.
TOTP-1	Medium	A junk recovery_code bypassed the 2FA lockout — the exemption keyed on the field's presence, and TOTP is checked first.
PK-1	Medium	signCount = 0 defeated clone detection and reset the ratchet permanently. Synced passkeys unaffected.
SUBJ-2	Low	Transliteration expands ~6× in bytes, so a valid identifier could overflow the column and 500 an unauthenticated route.
RELEASE-1	Low	lukk:release lower-cased user-id subjects, breaking ULIDs on Postgres/SQLite.
PG-1	Low	The insert-race catch was itself a 500 on Postgres. Now uses a savepoint.

Two test notes: the existing insert-race test was passing without exercising the race (its hook fired on the hasTable probe, so no INSERT collided), and LoginRateLimiter::subject() is removed as dead.

3. AUDIT.md

The previous audit's findings lived in an untracked directory and were lost — only the IDs survived. The register is in git now: fixed items, ~22 open ones with severity and rationale, and a verified sound section so the next audit doesn't re-derive it and a regression reads as a change.

Accepted residual, documented: the decaying throttle still keys on the normalized identifier, so look-alike accounts share a bucket and can throttle each other. It decays, grants no release primitive, and keying it on identity would put a provider lookup in front of every login attempt including unauthenticated floods.

Verification

305 passed (797 assertions), 100.0% coverage, Pint clean. 27ed9ee also verified to pass standalone (290 tests).

Docs in stsepelin/lukk-docs#8.

Greptile Summary

This PR adds per-user and per-IP throttling plus persistent lockout protection to step-up password confirmation, while correcting seven audited authentication and lockout defects.

• Keys persistent login lockouts by resolved account identity with a normalized fallback for unknown identifiers.
• Makes confirmation verification guard-aware and adds guard-scoped confirmation rate limiters.
• Corrects TOTP recovery-code exemption handling and passkey sign-counter regression detection.
• Repairs lockout release behavior and PostgreSQL insert-race recovery.
• Adds regression coverage and a tracked security audit register.

Confidence Score: 5/5

The PR appears safe to merge, with its authentication and lockout changes covered by focused regression tests and no actionable changed-code defect identified.

The new lockout subjects, guard-aware confirmation verification, confirmation throttles, counter handling, and PostgreSQL race recovery remain internally consistent across their routes, bindings, actions, and tests.

Important Files Changed

Filename	Overview
src/Actions/AttemptLogin.php	Derives one identity-based lockout subject for gating, failure recording, and release, and clears confirmation locks after successful password login.
src/Actions/ConfirmPassword.php	Adds persistent confirmation lock checks, failure counting, and successful-attempt release behavior.
src/Auth/LoginRateLimiter.php	Separates persistent identity subjects from normalized throttle identifiers and hashes byte-expanded normalized values.
src/Http/Middleware/RequireConfirmation.php	Verifies confirmation tokens using configuration for the guard that authenticated the request.
src/LukkServiceProvider.php	Registers default and extra-guard confirmation limiters with both IP and authenticated-user buckets.
src/Lockout/DatabaseLockoutRepository.php	Uses a nested transaction/savepoint so PostgreSQL unique-insert races can recover within the outer transaction.
src/Actions/FinishPasskeyLogin.php	Rejects counter regression after a positive sign count and prevents persisted counters from moving backward.
src/Actions/VerifyTwoFactorChallenge.php	Restricts the lockout exemption to recovery-code-only attempts so an attached junk code cannot bypass TOTP locking.
src/Console/ReleaseLockoutCommand.php	Resolves login subjects to account identities while preserving case-sensitive user IDs for two-factor and confirmation releases.
src/routes/api.php	Applies the new confirmation throttles to password and passkey confirmation endpoints.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Authenticated confirmation request] --> B{Route throttle permits?}
    B -- No --> C[429 response]
    B -- Yes --> D{Password confirmation?}
    D -- Yes --> E{Confirm lock held?}
    E -- Yes --> F[423 response]
    E -- No --> G{Password valid?}
    G -- No --> H[Record confirm failure]
    H --> I[422 response]
    G -- Yes --> J[Release confirm lock]
    D -- No, passkey --> K[Verify passkey assertion]
    J --> L[Issue guard-scoped confirmation token]
    K --> L
    L --> M[Protected route verifies token with active guard configuration]

Loading

_{Reviews (1): Last reviewed commit: "docs: add a tracked security audit regis..." | Re-trigger Greptile}