Open source
Refresh Tokens for Laravel
composer require roundly-consulting/refresh-tokens-for-laravelPrehľad
Nepriehľadné rotujúce refresh tokeny a relácie zariadení pre Laravel. Tokeny sa ukladajú len ako SHA-256 odtlačky, rotujú sa jediným atomickým dopytom typu compare-and-swap, takže zo súbežných obnovení uspeje práve jedno, a opätovné predloženie už použitého tokenu automaticky odvolá celú jeho rodinu. Akýkoľvek Authenticatable model — používatelia, API klienti, administrátori — drží relácie v jednej polymorfnej tabuľke so stabilným ID relácie, údajmi o zariadení a odhlásením „všade“ jedným volaním. Licencia MIT, bez runtime závislostí tretích strán — len Laravel a vlastné balíky Roundly pre kryptografiu, enumy a toolkit.
Čo získate
Hašované v databáze
Ukladá sa len SHA-256 odtlačok pod unikátnym indexom; plaintext dostanete raz. Voliteľne s HMAC pepperom.
Atomická rotácia
Jeden dopyt typu compare-and-swap: zo súbežných obnovení uspeje práve jedno — bez transakcie a bez zámku riadku.
Detekcia opätovného použitia
Opätovne predložený rotovaný token odvolá celú rodinu, zneplatní jej prístupové tokeny a spustí udalosť. Vždy zapnuté.
Relácie zariadení
Stabilné ID relácie pre každé prihlásenie, údaje o zariadení a polohe a odvolanie jednej, ostatných či všetkých relácií.
Polymorfní vlastníci
Používatelia, API klienti, administrátori — akýkoľvek Authenticatable model v jednej tabuľke, s obnovou obmedzenou na typ účtu.
Posuvná aj absolútna životnosť
Posuvné TTL pri každej rotácii plus pevný absolútny strop relácie, oboje nastaviteľné pre konkrétne prihlásenie.
Fasáda, DI alebo akcie
Jedna fasáda RefreshTokens nad injektovateľným manažérom a jednoúčelovými akciami, plus zaznamenávajúci fake, v ktorom každé volanie naozaj beží.
Dokumentácia
Inštalácia
Inštalácia cez Composer, publikovanie a spustenie migrácie a pridanie traitu HasRefreshTokens na každý model vlastníka.
Konfigurácia
Každý kľúč, predvolená hodnota a env premenná — tabuľka, typ kľúča, životnosti, dĺžka tokenu, hašovanie, tolerancia rotácie a čistenie.
Vlastníci a typy kľúčov
Polymorfní vlastníci: používatelia, API klienti a administrátori v jednej tabuľke, oddelení morph triedou a kľúčom, s kľúčmi bigint, UUID či ULID.
Fasáda RefreshTokens
Celá fasáda RefreshTokens na jednom mieste — vydanie, uplatnenie, rotácia, odvolanie a čistenie plus objekty sessions() a session().
DI a akcie
Namiesto fasády injektujte RefreshTokensManager alebo spustite akciu za ktoroukoľvek metódou — vždy beží ten istý kód.
Vydávanie tokenov
Vydajte refresh token prepojený s prístupovým tokenom cez IssueContext alebo fluentný builder; plaintext dostanete práve raz.
Uplatnenie a rotácia
Atomicky uplatnite token s ochranou proti dvojitému použitiu, rotujte ho jedným volaním, obmedzte obnovu na typ vlastníka a ošetrite zlyhania.
Detekcia opätovného použitia
Opätovne predložený rotovaný token odvolá celú rodinu, zneplatní jej prístupové tokeny a spustí RefreshTokenReuseDetected — vždy zapnuté.
Odvolanie a odhlásenie
Odhláste jeden token alebo všetky relácie, zaznamenajte dôvod cez RevocationReason a pri zmene hesla odvolajte všetko.
Relácie
Vypisujte, vyhľadávajte a odvolávajte relácie zariadení podľa stabilného ID rodiny — základ obrazovky „vaše zariadenia“.
Údaje o zariadení a polohe
Pripojte k relácii prehliadač, OS, typ zariadenia a polohu, ktoré spracovala aplikácia, cez enrich() — typicky z asynchrónneho jobu.
Odvolanie prístupových tokenov
Zaregistrujte AccessTokenRevoker, aby každá odvolaná relácia či rodina zneplatnila aj svoj prístupový token, napr. cez denylist JWT jti.
Udalosti
Štyri typované udalosti — vydanie, uplatnenie, odvolanie a detekcia zneužitia — len s ID a skalármi, nikdy s modelom či plaintextom.
Bezpečnosť a hašovanie
SHA-256 odtlačky v databáze, voliteľný HMAC pepper, validovaná konfigurácia, bezpečná serializácia a hranice zodpovednosti aplikácie.
Model tokenu
Scopes, pomocné metódy, casty a skryté atribúty modelu RefreshToken a náhrada vlastnou podtriedou.
Databázová schéma
Stĺpce tabuľky refresh_tokens a RefreshTokenBlueprint na zopakovanie či prevzatie schémy vo vlastnej migrácii.
Artisan príkazy
Čistite mŕtve tokeny podľa vlastného plánu cez refresh-tokens:prune alebo pomenovaný model:prune a konfiguráciu skontrolujte cez about.
Výnimky
Všetky typované výnimky balíka, kedy sa vyhadzujú a základná trieda, ktorou zachytíte všetky naraz.
Testovanie
RefreshTokens::fake() zaznamená každé vydanie, uplatnenie, rotáciu, odvolanie, obohatenie aj čistenie; zvyšok pokryje FakeAccessTokenRevoker a factory.
Požiadavky
PHP 8.4+ a Laravel 12 alebo 13, bez runtime závislostí tretích strán. Sprievodné balíky Roundly sa nainštalujú automaticky.
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.