NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Refresh Tokens for Laravel

Vydávanie tokenov

Aplikácia najprv vytvorí prístupový token a potom vydá refresh token prepojený s ním. Plaintext sa vráti len raz — uloží sa iba jeho odtlačok:

use RoundlyConsulting\RefreshTokens\Facades\RefreshTokens;
use RoundlyConsulting\RefreshTokens\DataTransferObjects\IssueContext;

$new = RefreshTokens::issue($user, new IssueContext(
    ipAddress: $request->ip(),
    userAgent: $request->userAgent(),
    accessReference: $access->jti, // opaque link to the host's access token
));

$plainText = $new->plainText;      // return to the client ONCE
$row = $new->token;                // the stored RefreshToken row (hash only)

Fluentný builder

RefreshTokens::for($owner) vracia builder PendingIssue pre bežný prípad v controlleri:

$new = RefreshTokens::for($user)
    ->fromRequest($request)        // fills ip + user agent
    ->linkedTo($access->jti)
    ->issue();
  • fromRequest($request) — vyplní IP adresu a user agent; prípadne ich nastavte samostatne cez withIp() a withUserAgent().
  • linkedTo($accessReference) — nepriehľadný odkaz na prístupový token.
  • inFamily($familyId) — zdedí existujúcu rodinu; startingFamily($uuid) — založí novú pod vaším UUID. Použite jedno alebo druhé.
  • ttl($seconds) / absoluteTtl($seconds) — životnosti pre konkrétnu reláciu.
  • meta(array) — metadáta relácie.
  • issue() — terminálne volanie; vracia NewRefreshToken.

Možnosti pre konkrétnu reláciu

Všetko je voliteľné — založte rodinu pod vlastným ID relácie, dajte tomuto prihláseniu vlastné životnosti a pripojte metadáta:

$sid = (string) Str::uuid();       // e.g. already minted into the access token as `sid`

$new = RefreshTokens::for($client)
    ->fromRequest($request)
    ->startingFamily($sid)         // root the family under YOUR uuid (IssueContext::$newFamilyId)
    ->ttl(3600)                    // sliding lifetime for this session
    ->absoluteTtl(86_400)          // hard cap for this session; 0 = uncapped
    ->meta(['guard' => 'clients', 'amr' => ['pwd', 'otp'], 'auth_time' => time()])
    ->issue();

newFamilyId musí byť platné UUID (kontroluje sa pred akýmkoľvek dopytom), ktoré ešte nepoužíva žiadna rodina. ID rodín sa normalizujú na malé písmená, takže sa na každom databázovom driveri porovnávajú bez ohľadu na veľkosť písmen.

IssueContext

Rovnaké možnosti ako DTO — každé pole je voliteľné:

$new = RefreshTokens::issue($owner, new IssueContext(
    ipAddress: $request->ip(),
    userAgent: $request->userAgent(),
    accessReference: $accessTokenId,   // opaque handle to the paired access token
    familyId: null,                    // inherit an existing family (rotation replacement)
    newFamilyId: null,                 // OR root a new family under a caller-chosen UUID
    ttl: null,                         // sliding lifetime override (>= 1 s)
    absoluteTtl: null,                 // absolute cap override, root only (>= 0; 0 = uncapped)
    meta: ['guard' => 'users', 'amr' => ['pwd'], 'auth_time' => time()],
));
PoleTypVýznam
ipAddress?stringIP klienta. Pri dedení rodiny sa pri hodnote null skopíruje z najnovšieho riadku rodiny.
userAgent?stringSurový reťazec user-agent; rovnaké dedenie ako pri ipAddress.
accessReference?stringNepriehľadný odkaz na prístupový token aplikácie (napr. JWT jti), pri odvolaní odovzdaný revokeru.
familyId?stringZdediť existujúcu rodinu toho istého vlastníka — náhrada pri rotácii.
newFamilyId?stringZaložiť novú rodinu pod vlastným UUID. Nedá sa kombinovať s familyId.
ttl?intPrepis posuvnej životnosti v sekundách (≥ 1).
absoluteTtl?intPrepis absolútneho stropu v sekundách (≥ 0; 0 = bez stropu). Platí len pri založení rodiny.
meta?arrayMetadáta relácie uložené ako JSON, pri dedení zlúčené. Nikdy do nich nevkladajte tajomstvá.

Metadáta relácie

meta sa ukladá ako JSON a dedí sa pri každej rotácii (nové kľúče sa zlúčia cez staré). Prečíta ho každý, kto má prístup k tabuľke, a serializuje sa spolu s modelom — nikdy doň nevkladajte tajomstvá. Na PostgreSQL (jsonb) sa poradie kľúčov objektu nezachováva.

Validácia

Vstupy sa validujú pred akýmkoľvek dopytom:

VstupVýnimka
familyId a newFamilyId narazInvalidTokenFamilyException::ambiguous
newFamilyId nie je UUIDInvalidTokenFamilyException::malformed
newFamilyId už používa iná rodinaInvalidTokenFamilyException::alreadyExists
familyId je chybné alebo nepatrí tomuto vlastníkoviInvalidTokenFamilyException::unknownForOwner
familyId bolo zrušené detekciou opätovného použitiaInvalidTokenFamilyException::reuseRevoked
familyId, ktorého najnovší riadok ukončilo odvolanieInvalidTokenFamilyException::ended
ttl < 1InvalidTokenConfigurationException::invalidTtl
absoluteTtl < 0InvalidTokenConfigurationException::invalidAbsoluteTtl

Úspešné vydanie spustí udalosť RefreshTokenIssued.

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 kryptomien

Odoslaní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.