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()],
));| Pole | Typ | Význam |
|---|---|---|
ipAddress | ?string | IP klienta. Pri dedení rodiny sa pri hodnote null skopíruje z najnovšieho riadku rodiny. |
userAgent | ?string | Surový reťazec user-agent; rovnaké dedenie ako pri ipAddress. |
accessReference | ?string | Nepriehľadný odkaz na prístupový token aplikácie (napr. JWT jti), pri odvolaní odovzdaný revokeru. |
familyId | ?string | Zdediť existujúcu rodinu toho istého vlastníka — náhrada pri rotácii. |
newFamilyId | ?string | Založiť novú rodinu pod vlastným UUID. Nedá sa kombinovať s familyId. |
ttl | ?int | Prepis posuvnej životnosti v sekundách (≥ 1). |
absoluteTtl | ?int | Prepis absolútneho stropu v sekundách (≥ 0; 0 = bez stropu). Platí len pri založení rodiny. |
meta | ?array | Metadá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:
| Vstup | Výnimka |
|---|---|
| familyId a newFamilyId naraz | InvalidTokenFamilyException::ambiguous |
| newFamilyId nie je UUID | InvalidTokenFamilyException::malformed |
| newFamilyId už používa iná rodina | InvalidTokenFamilyException::alreadyExists |
| familyId je chybné alebo nepatrí tomuto vlastníkovi | InvalidTokenFamilyException::unknownForOwner |
| familyId bolo zrušené detekciou opätovného použitia | InvalidTokenFamilyException::reuseRevoked |
| familyId, ktorého najnovší riadok ukončilo odvolanie | InvalidTokenFamilyException::ended |
| ttl < 1 | InvalidTokenConfigurationException::invalidTtl |
| absoluteTtl < 0 | InvalidTokenConfigurationException::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 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.