Model používateľa

Každý model, ktorý môže vlastniť prístupové kľúče (passkeys), implementuje kontrakt HasPasskeys; trait InteractsWithPasskeys je hotová implementácia. Najprv pridajte nullable a unikátny stĺpec pre nepriehľadný identifikátor používateľa bez osobných údajov — vytvorí ho Blueprint makro passkeyUserHandle() na ľubovoľnej tabuľke účtov, pomenovaný podľa passkeys.user.handle_column:

// database/migrations/xxxx_add_passkey_user_handle_to_users_table.php
Schema::table('users', function (Blueprint $table): void {
    $table->passkeyUserHandle();   // string(passkeys.user.handle_column)->nullable()->unique()
});

Potom upravte model:

use Illuminate\Foundation\Auth\User as Authenticatable;
use RoundlyConsulting\Passkeys\Concerns\InteractsWithPasskeys;
use RoundlyConsulting\Passkeys\Contracts\HasPasskeys;

final class User extends Authenticatable implements HasPasskeys
{
    use InteractsWithPasskeys;
}

Ak máte viac modelov účtov (guardov), pridajte stĺpec do každej tabuľky, ktorej model vlastní prístupové kľúče.

Kontrakt

Ceremónie potrebujú len tieto štyri metódy. Trait ich implementuje za vás; vlastnú implementáciu napíšte, ak potrebujete špecifické ukladanie identifikátora alebo odvodenie mena:

interface HasPasskeys
{
    public function passkeyUserHandle(): string;   // opaque, non-PII, stable per user
    public function passkeyUserName(): string;      // authenticator "name" (e.g. email)
    public function passkeyDisplayName(): string;   // authenticator "display name" (e.g. full name)
    public function passkeys(): MorphMany;          // the user's stored credentials
}

Ceremónie priamo na modeli

Trait sprístupňuje ceremónie aj ako metódy modelu, takže podmetom je samotný používateľ. Ide o skratky pre handle účtu — každá deleguje na Passkeys::for($this), takže ich vidia aj vaše prepísané akcie a Passkeys::fake():

$options = $user->passkeyRegistrationOptions();                   // Passkeys::for($user)->registrationOptions()
$passkey = $user->registerPasskey($response, 'MacBook Touch ID'); // ->register()
$options = $user->passkeyAuthenticationOptions($overrides);       // ->authenticationOptions()

$user->hasPasskeys();   // ->exists() — at least one active (non-revoked) passkey
$user->passkeyCount();  // ->count()

• passkeys() — MorphMany vzťah k uloženým kľúčom používateľa.
• passkeyRegistrationOptions(?RegistrationOptionsOverrides) — možnosti registrácie pre tohto používateľa.
• registerPasskey(RegistrationResponseData, ?string $name) — overí a uloží kľúč pre tohto používateľa.
• passkeyAuthenticationOptions(?AuthenticationOptionsOverrides) — možnosti prihlásenia viazané na kľúče tohto používateľa.
• hasPasskeys() / passkeyCount() — či a koľko aktívnych (neodvolaných) kľúčov účet má.

Identifikátor používateľa

Identifikátor sa generuje lenivo a uloží sa pri prvom volaní registrationOptions() alebo authenticationOptions() viazanom na používateľa — ide o malý zápis v inak čítacom volaní. Zápis je cielený:

• Mení len stĺpec s identifikátorom, takže neuložené zmeny na modeli zostanú neuložené — model sa znova neukladá.
• Vyplní len prázdny stĺpec, takže pri súbežných prvých požiadavkách vyhrá prvý uložený identifikátor a použijú ho všetky požiadavky.
• Nikdy nevloží neuložený model: na modeli, ktorý ešte neexistuje, sa identifikátor len nastaví a uloží ho až uloženie samotného modelu.

Vďaka tomu stačí na vopred vygenerovaný identifikátor jeden riadok — zavolajte passkeyUserHandle() pri vytváraní používateľa:

// e.g. in a User creating() observer
$user->passkeyUserHandle(); // sets base64url(random_bytes(passkeys.user.handle_bytes))

Ak identifikátory generujete sami, musia byť v base64url z náhodných bajtov — aspoň 16, bez zarovnania (padding) — napríklad Base64Url::encode(random_bytes(32)) s triedou RoundlyConsulting\Crypto\Codec\Base64Url. Ceremónia identifikátor dekóduje striktne, takže reťazec, ktorý ho len pripomína, napríklad Str::random(43), odmietne výnimkou InvalidClientData.

Identifikátor musí zostať stabilný. Prihlásenie viazané na používateľa porovnáva identifikátor uložený pri registrácii kľúča s hodnotou, ktorú vráti passkeyUserHandle(), takže jeho zmena používateľa odreže od prihlásení viazaných na účet. Prihlásenia bez mena to neovplyvní.

Meno a zobrazované meno

Autentifikátor zobrazuje názov účtu a zobrazované meno. Predvolene sú to atribúty email a name modelu (so záložnou hodnotou primárneho kľúča). Globálne ich presmerujete cez passkeys.user.name_attribute a display_name_attribute, alebo prepíšte metódy pre vlastnú logiku:

public function passkeyDisplayName(): string
{
    return trim($this->first_name.' '.$this->last_name) ?: $this->email;
}