Detekcia opätovného použitia

Predloženie už rotovaného tokenu — na redeem() či rotate(), alebo na revoke() (pozrite Odvolanie a odhlásenie) — je signál krádeže. Odvolá sa celá rodina tokenov, zaregistrovaný AccessTokenRevoker sa zavolá pre prístupový token každého živého člena a spustí sa RefreshTokenReuseDetected — všetko automaticky, bez konfiguračného prepínača:

$a = RefreshTokens::issue($user, new IssueContext(accessReference: 'acc-a'));
$rotation = RefreshTokens::rotate($a->plainText, new RotationContext(accessReference: 'acc-b'));

// The already-rotated token A is presented again — a theft signal:
RefreshTokens::redeem($a->plainText); // null — and the whole family is revoked

$rotation->newRefreshToken->token->fresh()->revoked_reason; // RevocationReason::ReuseDetected
// AccessTokenRevoker::revoke('acc-b') was called; RefreshTokenReuseDetected fired once

Odolné voči súbehom

• Verdikt o opätovnom použití sa zapíše do rodiny skôr, než ju odvolanie prehľadá, a prehľadávanie sa opakuje, kým jeden prechod nič neodvolá.
• Náhrada vydaná do rodiny v okamihu jej zrušenia sa odvolá sama, takže čerstvo rotovaný token reakciu na krádež neprežije v žiadnom poradí súbehu.
• Ak opakované predloženie príde, keď je rodina uprostred rotácie — jej najnovší riadok je už uplatnený, náhrada ešte nie je vložená — uzavrie sa aj táto relácia: uplatnený riadok dostane dôvod ReuseDetected, jeho prístupový token sa zneplatní a spustí sa SessionRevoked. Rozpracovaná náhrada sa odmietne (rotate() vráti null; výslovné issue() vyhodí InvalidTokenFamilyException).
• Pri predvolenom striktnom rotation.grace = 0 sem patrí aj porazený z dvoch súbežných uplatnení toho istého tokenu.
• Reakcia sa obmedzuje na vlastníka predloženého tokenu, takže ani ID rodiny, ktoré zasahuje dvoch vlastníkov, nedovolí, aby opakované predloženie jedného vlastníka odhlásilo druhého.

Tolerančné okno

Ak váš frontend legitímne predkladá token znova v krátkom okne (dve karty obnovujú naraz, opakovaná požiadavka), povoľte niekoľko sekúnd tolerancie. V rámci okna vráti opätovne predložený token null bez akéhokoľvek odvolania (odhlásenie s ním reláciu aj tak ukončí — pozrite Odvolanie a odhlásenie):

REFRESH_TOKENS_ROTATION_GRACE=30

Upozornenia

RefreshTokenReuseDetected sa spustí vždy, keď reakcia niečo ukončí — odvolá živého člena alebo uzavrie reláciu zachytenú uprostred rotácie, oboje sa započíta do revokedCount (≥ 1) — takže to, či krádež vyvolá upozornenie, nikdy nezávisí od načasovania. Opakované predloženie do rodiny, ktorá sa už skončila, nespustí nič, takže nezahltí vaše upozornenia prázdnymi udalosťami:

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\RefreshTokens\Events\RefreshTokenReuseDetected;

Event::listen(function (RefreshTokenReuseDetected $event): void {
    // $event->familyId, $event->ownerType, $event->ownerId, $event->revokedCount
    // alert your security channel, notify the account owner, …
});

Obmedzovanie požiadaviek zostáva na aplikácii — balík nelimituje predkladanie tokenov. Endpoint na obnovu obaľte middlewarom throttle z Laravelu, aby ste utlmili záplavy opakovaných pokusov.