Laravel Passkeys 初步調查（passkeys-server + @laravel/passkeys）

本文根據 laravel/passkeys-server 與 laravel/passkeys 的 README 進行初步調查。兩個套件仍處於未打 tag 的開發階段（2026 年 4 月時點）。

這是什麼套件

Laravel 官方儲存庫公開了兩個實作無密碼認證（WebAuthn / Passkey）的套件。

伺服器端（PHP）：laravel/passkeys-server
用戶端（JavaScript）：@laravel/passkeys

兩者組合可在 Laravel 應用中一致地實作 Passkey 註冊與 Passkey 登入。

伺服器端：`laravel/passkeys-server`

安裝與初始設定

加入 PHP 套件

composer require laravel/passkeys

發佈並執行 migration

php artisan vendor:publish --tag=passkeys-migrations
php artisan migrate

於 User Model 加上 trait 與 contract

use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;
}

視需要也可發佈設定檔。

php artisan vendor:publish --tag=passkeys-config

自動註冊的路由

分類	方法	路由	用途
Login (guest)	`GET`	`/passkeys/login/options`	取得認證選項
Login (guest)	`POST`	`/passkeys/login`	驗證 Passkey 並登入
Confirm (auth)	`GET`	`/passkeys/confirm/options`	取得確認用選項
Confirm (auth)	`POST`	`/passkeys/confirm`	Passkey 確認
Management (auth)	`GET`	`/user/passkeys/options`	取得註冊選項
Management (auth)	`POST`	`/user/passkeys`	儲存新 Passkey
Management (auth)	`DELETE`	`/user/passkeys/{passkey}`	刪除 Passkey

`config/passkeys.php` 主要選項

relying_party_id
allowed_origins
user_handle_secret
timeout
guard
middleware
throttle
redirect

事件

套件會發出以下事件。

PasskeyRegistered
PasskeyVerified
PasskeyDeleted

客製化點

LoginAuthorizationCallback（登入授權判定）

可用 Passkeys::authorizeLoginUsing() 控制驗證成功後是否允許登入。若要中止可回傳 false 或拋出 ValidationException。

CustomActions（替換 WebAuthn 處理）

可繼承 GenerateRegistrationOptions / GenerateVerificationOptions / StorePasskey / VerifyPasskey / DeletePasskey，並綁定到 Service Container 以替換行為。

CustomResponses（替換回應）

可自實作 PasskeyLoginResponse 等 contract，把成功時的回應（JSON、重新導向等）調整為符合應用需求。

用戶端：`@laravel/passkeys`

@laravel/passkeys 是處理瀏覽器 WebAuthn ceremony 的 JavaScript 用戶端。

安裝

npm install @laravel/passkeys

基本 API

import { Passkeys } from "@laravel/passkeys";

await Passkeys.register({ name: "My MacBook" });
await Passkeys.verify();

框架 helper

React：@laravel/passkeys/react 的 usePasskeyVerify、usePasskeyRegister
Vue：@laravel/passkeys/vue 的 usePasskeyVerify、usePasskeyRegister
Svelte：@laravel/passkeys/svelte 的 usePasskeyVerify、usePasskeyRegister

Passkey 自動填入

指定 autofill: true 可在具有 autocomplete="... webauthn" 的 input 上顯示瀏覽器的 Passkey picker。不支援的環境或使用者取消時，會退回一般流程。

型別化錯誤

README 中公開的錯誤類別如下。

NotSupportedError
UserCancelledError
PasskeyExistsError
PasskeyError（base class）

SSR 對應

WebAuthn 屬於瀏覽器 API，但各框架 hook 皆 SSR 安全。伺服器端 isSupported 會被視為 false，掛載後才更新為真正的瀏覽器狀態。

總結

組合 laravel/passkeys-server（PHP）與 @laravel/passkeys（JS），可在 Laravel 建構完整的 Passkey 認證堆疊。
兩者仍處於未打 tag 的開發階段，但作為 Laravel 官方生態系，未來很可能成為標準認證方式。
若要提早導入，安全的做法是以 README 中的路由、設定、錯誤處理、客製化擴充點為前提來設計。

之後 Passkey 正式作為 Laravel Fortify 的功能加入。透過 Fortify 啟用 Passkey 時，應使用 Features::passkeys()，而不是直接安裝 laravel/passkeys-server。詳情請參考 Laravel Fortify 與啟動套件。

laravel/passkeys-server

確認伺服器端套件的最新 README 與實作。