Záložné kódy

Každá aktivácia vygeneruje recovery_codes.count kódov (predvolene 8) v tvare XXXXX-XXXXX — dva päťznakové segmenty z A–Z a 0–9, bez písmena O, aby boli kódy na papieri jednoznačné. Vrátia sa raz, v $setup->recoveryCodes.

Použitie záložného kódu

Samostatné volanie netreba: attempt() skúsi záložné kódy, keď TOTP kontrola neprejde. Zhodný kód sa spotrebuje, vyvolá sa RecoveryCodeConsumed s počtom zostávajúcich kódov a výsledok hlási TwoFactorMethod::RecoveryCode:

use RoundlyConsulting\TwoFactor\Enums\TwoFactorMethod;
use RoundlyConsulting\TwoFactor\Facades\TwoFactor;

$result = TwoFactor::for($user)->attempt($request->string('code')->toString());

$result->verified;               // bool — TOTP (replay-safe) or a single-use recovery code
$result->method;                 // TwoFactorMethod::Totp | ::RecoveryCode | null on failure
$result->remainingRecoveryCodes; // int, after this attempt — "1 recovery code left"
$result->replayed;               // true when a valid code's timestep was already used

if ($result->method === TwoFactorMethod::RecoveryCode) {
    // e.g. notify the user, add 'recovery_code' to an amr claim
}

Spotreba znova načíta riadok pod transakčným zámkom a až potom odstráni zhodný kód, takže raz vylákaný kód sa nedá použiť dvakrát súbežnými požiadavkami. Záložné kódy sa prijímajú bez ohľadu na TOTP replay guard.

Tak, ako ich ľudia píšu

Záložné kódy sa porovnávajú tak, ako ich ľudia píšu: na veľkosti písmen, okolitých medzerách ani pomlčke (či medzere namiesto nej) nezáleží a zadané písmeno O sa číta ako nula, s ktorou si ho používateľ zamenil — kódy písmeno O nikdy neobsahujú. Každý zápis zodpovedá jedinému vydanému kódu a každý kód sa stále dá použiť len raz:

// The user was issued YWNLY-0J5BK and types it loosely:
$result = TwoFactor::for($user)->attempt('ywnly 0j5bk');

$result->verified; // true — the code is spent
$result->method;   // TwoFactorMethod::RecoveryCode

// 'YWNLY0J5BK', ' ywnly-0j5bk ' or 'YWNLY-OJ5BK' (a letter O for the zero)
// would have matched the same code — once.

Importovaný kód iného tvaru sa len oreže o okolité medzery a inak sa musí zhodovať presne.

Obnovenie kódov

use RoundlyConsulting\TwoFactor\Facades\TwoFactor;

$codes = TwoFactor::for($user)->recoveryCodes()->regenerate(); // new plaintext set — show once
$left  = TwoFactor::for($user)->recoveryCodes()->remaining();  // drive a "regenerate?" prompt

// The same two calls on the user model:
$codes = $user->regenerateTwoFactorRecoveryCodes();
$left  = $user->twoFactorRecoveryCodesRemaining();

Obnovenie nahradí celú sadu, vyvolá RecoveryCodesRegenerated a vráti nové kódy v čitateľnej podobe — ide o jedinú kópiu, zobrazte ich preto raz. remaining() číta uložený počet, takže používateľovi môžete ponúknuť obnovenie, keď kódy dochádzajú.

Hašované alebo šifrované ukladanie

Predvolený režim hashed ukladá jednosmerné haše cez Hash::make() — výpis databázy ani uniknutý APP_KEY nikdy neprezradia platné záložné kódy. Voliteľný režim encrypted uchováva kódy šifrované, takže ich po aktivácii môžete zobraziť znova, za cenu ich vratnosti pomocou APP_KEY:

'recovery_codes' => [
    'count' => 8,
    'storage' => 'encrypted', // 'hashed' (default) | 'encrypted'
],

Zmena režimu zneplatní už uložené kódy — recovery_codes.storage meňte len pri novej základni aktivácií a ak režim zmeníte, aktivovaným používateľom kódy obnovte.