> ## 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 모델 통합, 라우트, 설정, 이벤트, 프론트엔드 API, 타입이 부여된 오류, SSR 대응까지 정리합니다.

<Info>
  이 글은 `laravel/passkeys-server`와 `laravel/passkeys`의 README에 기반한 초기 조사입니다. 두 패키지는 아직 태그 없는 개발 단계입니다 (2026년 4월 시점).
</Info>

## 이것은 무엇에 관한 패키지인가

Laravel의 공식 리포지토리에서 패스워드리스 인증(WebAuthn / 패스키)을 구현하기 위한 2개의 패키지가 공개되어 있습니다.

* 서버 측 (PHP): [`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* 클라이언트 측 (JavaScript): [`@laravel/passkeys`](https://github.com/laravel/passkeys)

이 두 개를 조합하면 Laravel 앱에서 패스키 등록과 패스키 로그인을 일관되게 구현할 수 있습니다.

## 서버 측: `laravel/passkeys-server`

### 설치와 초기 셋업

<Steps>
  <Step title="PHP 패키지 추가">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="마이그레이션 공개 및 실행">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="User 모델에 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`           | 패스키 검증과 로그인 |
| Confirm (auth)    | `GET`    | `/passkeys/confirm/options` | 확인용 옵션 취득   |
| Confirm (auth)    | `POST`   | `/passkeys/confirm`         | 패스키 확인      |
| Management (auth) | `GET`    | `/user/passkeys/options`    | 등록 옵션 취득    |
| Management (auth) | `POST`   | `/user/passkeys`            | 신규 패스키 저장   |
| Management (auth) | `DELETE` | `/user/passkeys/{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`를 상속하여 서비스 컨테이너에 바인딩하고, 동작을 교체할 수 있습니다.
  </Accordion>

  <Accordion title="CustomResponses (응답 교체)">
    `PasskeyLoginResponse` 등의 컨트랙트를 독자적으로 구현하여, 성공 시 응답(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();
```

### 프레임워크 헬퍼

* React: `@laravel/passkeys/react`의 `usePasskeyVerify`, `usePasskeyRegister`
* Vue: `@laravel/passkeys/vue`의 `usePasskeyVerify`, `usePasskeyRegister`
* Svelte: `@laravel/passkeys/svelte`의 `usePasskeyVerify`, `usePasskeyRegister`

### 패스키 자동완성

`autofill: true`를 지정하면 `autocomplete="... webauthn"`을 가진 input에 브라우저의 패스키 피커를 표시할 수 있습니다. 지원되지 않는 환경이나 사용자 취소 시에는 일반 흐름으로 폴백합니다.

### 타입이 부여된 오류

README에서는 다음 오류 클래스가 공개되어 있습니다.

* `NotSupportedError`
* `UserCancelledError`
* `PasskeyExistsError`
* `PasskeyError` (베이스 클래스)

### SSR 대응

WebAuthn은 브라우저 API이지만, 각 프레임워크용 훅은 SSR 세이프입니다. 서버 측에서는 `isSupported`가 `false`로 취급되고, 마운트 후에 실제 브라우저 상태로 갱신됩니다.

## 정리

* `laravel/passkeys-server` (PHP)와 `@laravel/passkeys` (JS)를 조합하면, Laravel에서 완결되는 패스키 인증 스택을 구축할 수 있습니다.
* 둘 다 태그 없는 개발 단계이지만, Laravel 공식 에코시스템으로서 앞으로의 표준 인증 수단이 될 가능성이 높습니다.
* 조기 채용하는 경우, README의 라우트 · 설정 · 오류 핸들링 · 커스터마이즈 확장점을 전제로 설계하면 안전합니다.

<Info>
  그 후 패스키는 **Laravel Fortify의 기능으로 정식 추가되었습니다**. Fortify 경유로 패스키를 활성화하는 경우는 `laravel/passkeys-server`를 직접 설치하지 않고 `Features::passkeys()`를 사용합니다. 자세한 내용은 [Laravel Fortify와 스타터 킷](/ko/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="/ko/advanced/fortify">
  Fortify 경유의 패스키 활성화 절차와 스타터 킷과의 관계를 설명합니다.
</Card>


## Related topics

- [Laravel Fortify와 스타터 킷](/ko/advanced/fortify.md)
- [Laravel Chisel — 스타터 킷의 포스트 인스톨 스크립트 라이브러리](/ko/blog/chisel-introduction.md)
- [2026년 4월 Laravel 업데이트](/ko/blog/changelog/202604.md)
- [laravel/ui에서 Fortify로의 마이그레이션 가이드](/ko/blog/ui-to-fortify.md)
- [Laravel LSP — Language Server Protocol에 의한 IDE 기능 확장](/ko/blog/laravel-lsp-introduction.md)