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

# Investigación inicial de Laravel Passkeys (passkeys-server + @laravel/passkeys)

> Investigación inicial de laravel/passkeys-server (PHP) y @laravel/passkeys (npm). Organizamos la instalación, la integración con el modelo User, las rutas, la configuración, los eventos, la API de frontend, los errores tipados y el soporte SSR.

<Info>
  Este artículo es una investigación inicial basada en los README de `laravel/passkeys-server` y `laravel/passkeys`. Ambos paquetes se encuentran en fase de desarrollo sin tags (a fecha de abril de 2026).
</Info>

## ¿Qué son estos paquetes?

En repositorios oficiales de Laravel se han publicado dos paquetes para implementar autenticación sin contraseña (WebAuthn / passkeys).

* Lado servidor (PHP): [`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* Lado cliente (JavaScript): [`@laravel/passkeys`](https://github.com/laravel/passkeys)

Combinándolos, puedes implementar de forma coherente en una app Laravel el registro y el login con passkeys.

## Lado servidor: `laravel/passkeys-server`

### Instalación y configuración inicial

<Steps>
  <Step title="Añade el paquete PHP">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="Publica y ejecuta las migraciones">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="Añade el trait y el contract al modelo User">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

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

Si lo necesitas, también puedes publicar el archivo de configuración.

```bash theme={null}
php artisan vendor:publish --tag=passkeys-config
```

### Rutas registradas automáticamente

| Categoría         | Método   | Ruta                        | Rol                                   |
| ----------------- | -------- | --------------------------- | ------------------------------------- |
| Login (guest)     | `GET`    | `/passkeys/login/options`   | Obtiene las opciones de autenticación |
| Login (guest)     | `POST`   | `/passkeys/login`           | Verifica la passkey e inicia sesión   |
| Confirm (auth)    | `GET`    | `/passkeys/confirm/options` | Obtiene las opciones de confirmación  |
| Confirm (auth)    | `POST`   | `/passkeys/confirm`         | Confirmación con passkey              |
| Management (auth) | `GET`    | `/user/passkeys/options`    | Obtiene las opciones de registro      |
| Management (auth) | `POST`   | `/user/passkeys`            | Guarda una nueva passkey              |
| Management (auth) | `DELETE` | `/user/passkeys/{passkey}`  | Elimina una passkey                   |

### Principales opciones de `config/passkeys.php`

* `relying_party_id`
* `allowed_origins`
* `user_handle_secret`
* `timeout`
* `guard`
* `middleware`
* `throttle`
* `redirect`

### Eventos

El paquete dispara los siguientes eventos.

* `PasskeyRegistered`
* `PasskeyVerified`
* `PasskeyDeleted`

### Puntos de personalización

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback (decisión de autorización de login)">
    Con `Passkeys::authorizeLoginUsing()` puedes controlar la autorización de login tras una verificación exitosa. Si quieres detenerla, devuelve `false` o lanza una `ValidationException`.
  </Accordion>

  <Accordion title="CustomActions (sustitución del procesamiento WebAuthn)">
    Puedes extender `GenerateRegistrationOptions` / `GenerateVerificationOptions` / `StorePasskey` / `VerifyPasskey` / `DeletePasskey`, enlazarlos en el service container y sustituir el comportamiento.
  </Accordion>

  <Accordion title="CustomResponses (sustitución de respuestas)">
    Implementa por tu cuenta contratos como `PasskeyLoginResponse` para adaptar la respuesta en caso de éxito (JSON, redirect, etc.) a los requisitos de tu app.
  </Accordion>
</AccordionGroup>

## Lado cliente: `@laravel/passkeys`

`@laravel/passkeys` es un cliente JavaScript que maneja la ceremonia WebAuthn del lado del navegador.

### Instalación

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

### API básica

```js theme={null}
import { Passkeys } from "@laravel/passkeys";

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

### Helpers por framework

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

### Autocompletado de passkeys

Al indicar `autofill: true`, en los inputs que tengan `autocomplete="... webauthn"` se puede mostrar el selector de passkeys del navegador. En entornos no soportados o si el usuario cancela, cae al flujo normal.

### Errores tipados

En el README se publican las siguientes clases de error.

* `NotSupportedError`
* `UserCancelledError`
* `PasskeyExistsError`
* `PasskeyError` (clase base)

### Soporte SSR

WebAuthn es una API del navegador, pero los hooks de cada framework son SSR-safe. En el lado servidor `isSupported` se trata como `false` y, tras el mount, se actualiza al estado real del navegador.

## Conclusión

* Combinando `laravel/passkeys-server` (PHP) y `@laravel/passkeys` (JS), se puede construir en Laravel una stack de autenticación con passkeys completa.
* Ambos están en fase de desarrollo sin tags, pero, como ecosistema oficial de Laravel, existe una alta probabilidad de que se conviertan en el método de autenticación estándar en el futuro.
* Si vas a adoptarlo pronto, es prudente diseñar teniendo como referencia las rutas, la configuración, el manejo de errores y los puntos de extensibilidad del README.

<Info>
  Posteriormente, passkeys se ha **añadido oficialmente como funcionalidad de Laravel Fortify**. Si activas las passkeys vía Fortify, en lugar de instalar directamente `laravel/passkeys-server`, usa `Features::passkeys()`. Consulta los detalles en [Laravel Fortify y los starter kits](/es/advanced/fortify).
</Info>

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  Consulta el README más reciente y la implementación del paquete del lado servidor.
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  Consulta el README más reciente y la API del paquete del lado cliente.
</Card>

<Card title="Laravel Fortify y los starter kits" icon="shield-check" href="/es/advanced/fortify">
  Se explican el procedimiento para activar passkeys vía Fortify y la relación con los starter kits.
</Card>


## Related topics

- [Laravel Fortify y los starter kits](/es/advanced/fortify.md)
- [Actualización de Laravel — Abril de 2026](/es/blog/changelog/202604.md)
- [Guía de migración de laravel/ui a Fortify](/es/blog/ui-to-fortify.md)
- [Laravel Chisel — Biblioteca de scripts de post-instalación para starter kits](/es/blog/chisel-introduction.md)
- [Laravel LSP — Extensión de funciones de IDE con Language Server Protocol](/es/blog/laravel-lsp-introduction.md)