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

• Odvolanie rodiny 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á — predložený riadok sa označí ako ReuseDetected a 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.

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í, len ak čistenie naozaj niečo odvolá (revokedCount > 0), takže opakované predkladanie už mŕtveho tokenu 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.