> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 初步調查 laravel/passkeys-server（PHP）與 @laravel/passkeys（npm）。整理安裝、User Model 整合、路由、設定、事件、前端 API、型別化錯誤與 SSR 對應。

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

## 這是什麼套件

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

* 伺服器端（PHP）：[`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* 用戶端（JavaScript）：[`@laravel/passkeys`](https://github.com/laravel/passkeys)

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

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

### 安裝與初始設定

<Steps>
  <Step title="加入 PHP 套件">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="發佈並執行 migration">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="於 User Model 加上 trait 與 contract">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

    class User extends Authenticatable implements PasskeyUser
    {
        use PasskeyAuthenticatable;
    }
    ```
  </Step>
</Steps>

視需要也可發佈設定檔。

```bash theme={null}
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`

### 客製化點

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback（登入授權判定）">
    可用 `Passkeys::authorizeLoginUsing()` 控制驗證成功後是否允許登入。若要中止可回傳 `false` 或拋出 `ValidationException`。
  </Accordion>

  <Accordion title="CustomActions（替換 WebAuthn 處理）">
    可繼承 `GenerateRegistrationOptions` / `GenerateVerificationOptions` / `StorePasskey` / `VerifyPasskey` / `DeletePasskey`，並綁定到 Service Container 以替換行為。
  </Accordion>

  <Accordion title="CustomResponses（替換回應）">
    可自實作 `PasskeyLoginResponse` 等 contract，把成功時的回應（JSON、重新導向等）調整為符合應用需求。
  </Accordion>
</AccordionGroup>

## 用戶端：`@laravel/passkeys`

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

### 安裝

```bash theme={null}
npm install @laravel/passkeys
```

### 基本 API

```js theme={null}
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 中的路由、設定、錯誤處理、客製化擴充點為前提來設計。

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

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  確認伺服器端套件的最新 README 與實作。
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  確認用戶端套件的最新 README 與 API。
</Card>

<Card title="Laravel Fortify 與啟動套件" icon="shield-check" href="/zh-TW/advanced/fortify">
  解說透過 Fortify 啟用 Passkey 的步驟與其與啟動套件的關係。
</Card>


## Related topics

- [部落格](/zh-TW/blog/index.md)
- [Laravel Fortify 與啟動套件](/zh-TW/advanced/fortify.md)
- [博客](/zh-CN/blog/index.md)
- [Laravel Chisel — 啟動套件的安裝後腳本函式庫](/zh-TW/blog/chisel-introduction.md)
- [laravel/symfony-on-cloud — 在 Laravel Cloud 上執行 Symfony 應用](/zh-TW/blog/symfony-on-cloud-introduction.md)