Laragear WebAuthn

https://github.com/laragear/webauthn
Admin
Laragear WebAuthn is a Laravel package that enables passwordless authentication using WebAuthn...
Tokens:71,529
Snippets:517
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and migrate WebAuthn

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Install the WebAuthn configuration, routes, and migration files, then run the migration to create the table for WebAuthn credentials (passkeys).

```shell
php artisan webauthn:install
```

```shell
php artisan migrate
```

--------------------------------

### ClientDataJson Usage Example

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/json-transport.md

Example of instantiating ClientDataJson and validating the type property.

```php
use Laragear\WebAuthn\ByteBuffer;
use Laragear\WebAuthn\ClientDataJson;

$clientData = new ClientDataJson('webauthn.get', 'https://securebank.com', ByteBuffer::fromBase64Url($rawChallenge));

if ($clientData->type !== 'webauthn.get') {
    return response()->abort(422);
}
```

--------------------------------

### Install laragear/webauthn with Composer

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Install the package into your Laravel project using Composer. Requires PHP 8.3 or later and Laravel 12 or later.

```bash
composer require laragear/webauthn
```

--------------------------------

### Use afterUp() and beforeDown() for migration hooks

Source: https://github.com/laragear/webauthn/blob/5.x/DATABASE.md

Execute logic after creating the table and before dropping it using afterUp() and beforeDown(). This example adds a foreign key on up and drops it on down.

```php
use Illuminate\Database\Schema\Blueprint;
use Laragear\Package\Models\Car;

return Car::migration()
    ->afterUp(function (Blueprint $table) {
        $table->foreignId('sociable_id')->references('id')->on('users');
    })
    ->beforeDown(function (Blueprint $table) {
        $table->dropForeign('sociable_id');
    });
```

--------------------------------

### Auth configuration for eloquent-webauthn driver

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/service-provider.md

Example auth.php configuration to use the 'eloquent-webauthn' driver. The password_fallback option defaults to true if not set.

```php
// auth.php
return [
    'providers' => [
        'users' => [
            'driver' => 'eloquent-webauthn',
            'model' => App\User::class,
            'password_fallback' => true,
        ],
    ],
];
```

--------------------------------

### Configure ceremony with enums

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/enums.md

Non-trivial usage example: configures a ceremony programmatically with enums, setting residentKey and userVerification to Required, which maps to authenticatorSelection fields.

```php
use Laragear\WebAuthn\Attestation\Creator\AttestationCreation;
use Laragear\WebAuthn\Enums\ResidentKey;
use Laragear\WebAuthn\Enums\UserVerification;

$creation = new AttestationCreation(
    user: $request->user(),
    residentKey: ResidentKey::Required,            // authenticatorSelection.residentKey = 'required'
    userVerification: UserVerification::Required,  // authenticatorSelection.userVerification = 'required'
);
```

--------------------------------

### Install @laragear/webpass via npm

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Install the @laragear/webpass package as a dependency for frontend frameworks like Vue, React, Angular, or Svelte.

```shell
npm i @laragear/webpass@2
```

--------------------------------

### Configure WebAuthn environment variables

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/configuration.md

Example environment variables for configuring the WebAuthn Relying Party. WEBAUTHN_NAME overrides the Relying Party name, WEBAUTHN_ID sets the Relying Party ID/domain, and WEBAUTHN_ORIGINS adds comma-separated additional origins.

```dotenv
WEBAUTHN_NAME=SecureBank
WEBAUTHN_ID=auth.securebank.com
WEBAUTHN_ORIGINS=mirror-myapp.com,android:apk-key-hash:kffL-daBUxvHpY-4M8yhTavt5QnFEI2LsexohxrGPYU
```

--------------------------------

### AssertedRequest Login Implementation

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/http-requests.md

Example of using the login() method within a controller to authenticate a user based on the request.

```php
use Laragear\WebAuthn\Http\Requests\AssertedRequest;

public function login(AssertedRequest $request)
{
    $user = $request->login();

    return $user
        ? response("Welcome back, $user->name!")
        : response('Something went wrong, try again!');
}
```

--------------------------------

### Assertion challenge options response

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

Example JSON response from POST {assert}/options when a user is found. Shows the challenge, timeout, rpId, userVerification, and allowCredentials fields returned by the AssertionCreator pipeline.

```json
{
  "challenge": "sMeblZkPwP3wc_FTR0eQ9gy7_qF5G5r8F9t1Kb2yq",
  "timeout": 60000,
  "rpId": "auth.securebank.com",
  "userVerification": "discouraged",
  "allowCredentials": [{"id": "q1w2e3r4…", "type": "public-key", "transports": ["usb", "nfc"]}]
}
```

--------------------------------

### Handle multiple exception types distinctly

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/exceptions.md

Non-trivial example that reacts to library failures (AssertionException, AttestationException, WebAuthnException) and non-library failures (InvalidArgumentException) with different HTTP responses.

```php
use Laragear\WebAuthn\Contracts\WebAuthnException;
use Laragear\WebAuthn\Exceptions\AssertionException;
use Laragear\WebAuthn\Exceptions\AttestationException;
use InvalidArgumentException;

try {
    $creation = $attestationCreator->send($attestation)->thenReturn();
} catch (AssertionException|AttestationException $e) {
    return response()->json(['errors' => $e->errors()], 422);
} catch (WebAuthnException $e) {
    return response()->abort(500, 'WebAuthn internal failure');
} catch (InvalidArgumentException $e) {
    return response()->abort(422, $e->getMessage());
}
```

--------------------------------

### Catch AssertionException and get errors

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/exceptions.md

Basic example that catches a failed assertion and retrieves the error message bag using the errors() method.

```php
use Laragear\WebAuthn\Exceptions\AssertionException;

try {
    $validator->send($validation)->thenReturn();
} catch (AssertionException $e) {
    $errors = $e->errors(); // ['assertion' => ['Assertion Error: Response challenge is not equal.']]
}
```

--------------------------------

### Authenticate user with AssertedRequest

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Example controller method that uses the AssertedRequest to authenticate a user with a passkey and returns a JSON welcome message.

```php
// App\Http\Controllers\LoginController.php
use Laragear\WebAuthn\Http\Requests\AssertedRequest;

public function login(AssertedRequest $request)
{
    $user = $request->login();

    return response()->json(['message' => "Welcome back, $user->name!"]);
}
```

--------------------------------

### AttestationRequest Typical Usage

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/http-requests.md

Example of using AttestationRequest in a controller method to configure fast registration and return the creation response.

```php
use Laragear\WebAuthn\Http\Requests\AttestationRequest;

public function options(AttestationRequest $request)
{
    return $request->fastRegistration()->toCreate();
}
```

--------------------------------

### Attestation Challenge Response JSON

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

Example JSON response for the attestation challenge endpoint. Shows the structure returned by the AttestationCreator pipeline, including relying party info, user descriptor, challenge, timeout, accepted algorithms, and authenticator selection options.

```json
{
  "rp": {"name": "SecureBank", "id": "securebank.com"},
  "user": {"id": "0e4b2f7a…", "name": "john@doe.com", "displayName": "John Doe"},
  "challenge": "aQn8wR2…",
  "timeout": 60000,
  "pubKeyCredParams": [{"type": "public-key", "alg": -7}, {"type": "public-key", "alg": -257}, {"type": "public-key", "alg": -8}],
  "attestation": "none",
  "authenticatorSelection": {"userVerification": "preferred", "residentKey": "preferred", "requireResidentKey": false},
  "excludeCredentials": [{"id": "q1w2…", "type": "public-key"}]
}
```

--------------------------------

### Customizing user descriptor in AttestationRequest::using()

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/web-authn-data.md

Example of customizing the user descriptor inside an AttestationRequest::using() callback, appending a counter when multiple credentials are allowed.

```php
// app\Http\Controllers\WebAuthn\WebAuthnRegisterController.php
use App\Models\User;
use Illuminate\Support\Str;
use Laragear\WebAuthn\Http\Requests\AttestationRequest;
use Laragear\WebAuthn\WebAuthnData;

public function registerDevice(AttestationRequest $request)
{
    return $request
        ->allowDuplicates()
        ->using(fn (User $user, bool $usesUniqueCredentials) {
            $counter = $usesUniqueCredentials
                ? ' #'. $user->webAuthnCredentials()->whereEnabled()->count() + 1
                : '';

            $displayName = $user->alias ?? $user->name ?? Str::before($user->email, '@');

            return WebAuthnData::make(
                name: $user->email,
                displayName: $displayName . $counter
            );
        })
        ->toCreate();
}
```

--------------------------------

### Customize WebAuthn name and display name with AttestationRequest::using

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Use the `using` callback on `AttestationRequest` to customize the WebAuthn name and display name at runtime. The callback receives the user instance and a boolean indicating if unique credentials are used, and must return a `WebAuthnData` instance. This example adds a counter to the display name when unique credentials are not used.

```php
// app\Http\Controllers\WebAuthn\WebAuthnRegisterController.php
use App\Models\User;
use Illuminate\Support\Str;
use Laragear\WebAuthn\Http\Requests\AttestationRequest;
use Laragear\WebAuthn\WebAuthnData;

public function registerDevice(AttestationRequest $request)
{
    return $request->using(function (User $user, bool $usesUniqueCredentials) {
        // If it doesn't use unique credentials, add a counter for how many he has
        $counter = $usesUniqueCredentials
            ? ' #'. $user->webAuthnCredentials()->whereEnabled()->count() + 1
            : '';
            
        $displayName = $user->alias ?? $user->name ?? Str::before($user->email, '@');
    
        return WebAuthnData::make(
            name: $user->email,
            displayName: $displayName . $counter
        );
    })->make();
}
```

--------------------------------

### Challenge::make()

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/challenge.md

Creates a new Challenge with custom binary data.

```APIDOC
## Challenge::make()

### Description
Creates a new Challenge with custom binary data.

### Method
`make()` (static)

### Signature
```php
public static function make(string $binary, int $timeout): static
```

### Parameters
- **$binary** (string) - Required - The custom binary challenge data
- **$timeout** (int) - Required - Challenge validity in seconds

### Return Value
- **static** - A new Challenge instance created via `new static(new ByteBuffer($binary), $timeout)`.
```

--------------------------------

### Basic usage of WebAuthnData::make()

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/web-authn-data.md

Shows the default factory usage, creating a WebAuthnData instance and converting it to JSON.

```php
use Laragear\WebAuthn\WebAuthnData;

$data = WebAuthnData::make('john@doe.com', 'John Doe');

response()->json($data->toArray()); // {"name":"john@doe.com","displayName":"John Doe"}
```

--------------------------------

### POST {attest}/options

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

Creates a WebAuthn attestation challenge for registering a new authenticator. Requires authentication; unauthenticated requests fail with HTTP 403.

```APIDOC
## POST {attest}/options

### Description
Creates a WebAuthn attestation challenge for registering a new authenticator. Requires authentication; unauthenticated requests fail with HTTP 403.

### Method
POST

### Endpoint
{attest}/options

### Parameters
#### Path Parameters
- **attest** (string) - Required - The attestation endpoint prefix.

#### Request Body
None.

### Response
#### Success Response (200)
- **rp.name** (string) - Always present. Relying party name.
- **rp.id** (string) - Present when `webauthn.relying_party.id` is configured. Relying party ID.
- **user.id** (string) - Always present. Hex UUID for the user.
- **user.name** (string) - Always present. User name.
- **user.displayName** (string) - Always present. User display name.
- **challenge** (string) - Always present. Base64url-encoded challenge.
- **timeout** (int) - Always present. Timeout in milliseconds.
- **pubKeyCredParams** (array) - Always present. Array of objects with `type` and `alg` fields.
- **attestation** (string) - Always present. Set to `'none'`.
- **authenticatorSelection.userVerification** (string) - Always present. User verification requirement.
- **authenticatorSelection.residentKey** (string) - Always present. Resident key preference.
- **authenticatorSelection.requireResidentKey** (bool) - Always present. Whether resident key is required.
- **excludeCredentials** (array) - Present by default when `allowDuplicates()` is not used. Array of excluded credentials.

#### Response Example
```json
{
  "rp": {"name": "SecureBank", "id": "securebank.com"},
  "user": {"id": "0e4b2f7a…", "name": "john@doe.com", "displayName": "John Doe"},
  "challenge": "aQn8wR2…",
  "timeout": 60000,
  "pubKeyCredParams": [{"type": "public-key", "alg": -7}, {"type": "public-key", "alg": -257}, {"type": "public-key", "alg": -8}],
  "attestation": "none",
  "authenticatorSelection": {"userVerification": "preferred", "residentKey": "preferred", "requireResidentKey": false},
  "excludeCredentials": [{"id": "q1w2…", "type": "public-key"}]
}
```
```

--------------------------------

### AttestedRequest Typical Usage

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/http-requests.md

Example of using AttestedRequest within a controller method to validate and save a credential.

```php
use Laragear"));

public function register(AttestedRequest $request)
{
    $request->validate(['alias' => 'nullable|string']);

    $id = $request->save($request->only('alias'));

    return response()->json(['id' => $id]);
}
```

--------------------------------

### POST {assert}/options

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

Documentation for the POST {assert}/options endpoint that creates a WebAuthn assertion challenge for login.

```APIDOC
## POST {assert}/options

### Description
Creates a WebAuthn assertion challenge for login. The user may be identified by an optional email; otherwise a userless (public-key) challenge is issued.

### Method
POST

### Endpoint
{assert}/options

### Parameters
#### Request Body
- **email** (string) - Optional - Email/identifier to locate the user and restrict allowCredentials.

### Request Example
{
  "email": "user@example.com"
}

### Response
#### Success Response (200)
- **challenge** (string) - Always - base64url ByteBuffer challenge.
- **timeout** (int) - Always - Timeout in milliseconds.
- **rpId** (string) - When webauthn.relying_party.id is configured - Relying party ID.
- **userVerification** (string) - When fastLogin()/secureLogin() used or userVerification set - User verification requirement (preferred/discouraged/required).
- **allowCredentials** (array) - When a user was found - Array of allowed credentials with id, type, and optional transports.

#### Response Example
{
  "challenge": "sMeblZkPwP3wc_FTR0eQ9gy7_qF5G5r8F9t1Kb2yq",
  "timeout": 60000,
  "rpId": "auth.securebank.com",
  "userVerification": "discouraged",
  "allowCredentials": [{"id": "q1w2e3r4…", "type": "public-key", "transports": ["usb", "nfc"]}]
}

### Error Handling
- **422** - Input validation failure (malformed email).
- **500** - Container errors (BindingResolutionException).
```

--------------------------------

### AssertionRequest Typical Usage

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/http-requests.md

Example of using AssertionRequest in a controller method to validate input and return the assertion challenge.

```php
use Laragear\WebAuthn\Http\Requests\AssertionRequest;

public function options(AssertionRequest $request)
{
    $request->validate(['email' => 'sometimes|email|string']);

    return $request->fastLogin()->toVerify($request->only('email'));
}
```

--------------------------------

### Fast registration with AttestationRequest::fastRegistration()

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Override the default user verification behavior to only check for user presence if possible. Use `fastRegistration()` before `toCreate()` when you want faster registration without active user verification.

```php
// app\Http\Controllers\WebAuthn\WebAuthnRegisterController.php
use Laragear\WebAuthn\Http\Requests\AttestationRequest;

public function createChallenge(AttestationRequest $request)
{
    return $request->fastRegistration()->toCreate();
}
```

--------------------------------

### Bind custom WebAuthnChallengeRepository in bootstrap/app.php

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/configuration.md

Replace the default session-based challenge repository with a custom one in bootstrap/app.php. The binding uses singleton() and only applies when nothing else is bound (bindIf).

```php
// bootstrap/app.php
use App\WebAuthn\MyRepository;
use Illuminate\Foundation\Application;
use Laragear\WebAuthn\Contracts\WebAuthnChallengeRepository;

return Application::configure(basePath: dirname(__DIR__))
    ->registered(function ($app) {
        $app->singleton(WebAuthnChallengeRepository::class, fn () => new MyRepository());
    })
    ->create();
```

--------------------------------

### Access morph relation on Car

Source: https://github.com/laragear/webauthn/blob/5.x/DATABASE.md

Example of accessing a morph relation. The owner attribute returns either a Company or Person model.

```php
use Laragear\Package\Models\Car;

$car = Car::find(1);

$owners = $car->owner; // App/Models/Company or App/Models/Person
```

--------------------------------

### Configure relying party name and ID

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Configuration for the relying party. The name defaults to the application name, and the ID is recommended to be the site domain. If null, the device may fill it internally.

```php
return [
    'relying_party' => [
        'name' => env('WEBAUTHN_NAME', env('APP_NAME')),
        'id'   => env('WEBAUTHN_ID'),
    ],
];
```

--------------------------------

### Add relationship with Car::resolveRelationUsing()

Source: https://github.com/laragear/webauthn/blob/5.x/DATABASE.md

Add a relationship to the model using resolveRelationUsing() in bootstrap/app.php. This example adds a 'driver' belongsTo relationship.

```php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Vendor\Package\Models\Driver;

return Application::configure(basePath: dirname(__DIR__))
    ->booted(function () {
        // Add the relationship.
        Car::resolveRelationUsing('driver', function (Car $car) {
            return $car->belongsTo(Driver::class, 'driver_id')
        })
    })->create();
```

--------------------------------

### Register custom challenge repository in bootstrap/app.php

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Replaces the default challenge repository resolver in the application container by binding the custom MyRepository class as a singleton. Place this in the registered() method of bootstrap/app.php.

```php
use App\WebAuthn\MyRepository;
use Illuminate\Foundation\Application;
use Laragear\WebAuthn\Contracts\WebAuthnChallengeRepository;

return Application::configure(basePath: dirname(__DIR__))
    ->registered(function ($app) {
        $app->singleton(WebAuthnChallengeRepository::class, fn () => new MyRepository())
    })
    ->create();
```

--------------------------------

### WebAuthnData::__construct

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/web-authn-data.md

Creates a new WebAuthnData instance with the user name and display name.

```APIDOC
## WebAuthnData::__construct

### Description
Creates a new WebAuthnData instance with the user name and display name.

### Method
Constructor

### Signature
```php
public function __construct(readonly protected string $name, readonly protected string $displayName)
```

### Parameters
- **$name** (string) - Required - The user name shown for the WebAuthn credential (usually the email)
- **$displayName** (string) - Required - The display name shown for the WebAuthn credential

### Return
No return value (constructor).
```

--------------------------------

### Assertion failure response payload

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

Example failure payload returned by Laravel when the assertion fails, showing the validation error message for the 'assertion' field.

```json
{ "assertion": ["Assertion Error: Response challenge is not equal."] }
```

--------------------------------

### Allow duplicate credentials with AttestationRequest::allowDuplicates()

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Allow multiple credentials per device by always returning an empty list of credentials to exclude. Use `allowDuplicates()` before `make()` to let the authenticator create a new credential even if one already exists.

```php
// app\Http\Controllers\WebAuthn\WebAuthnRegisterController.php
use Laragear\WebAuthn\Http\Requests\AttestationRequest;

public function registerDevice(AttestationRequest $request)
{
    return $request->allowDuplicates()->make();
}
```

--------------------------------

### Basic enum value assertion

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/enums.md

Basic usage example: asserts a server-side preference enum value by comparing the request input to UserVerification::Required->value.

```php
use Laragear\WebAuthn\Enums\UserVerification;

if ($request->input('userVerification') === UserVerification::Required->value) {
    // server demands active user verification
}
```

--------------------------------

### POST /login/options

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/http-requests.md

Handles the assertion challenge request for WebAuthn login. Produces the assertion challenge.

```APIDOC
## POST /login/options

### Description
Handles the assertion challenge request for WebAuthn login. Produces the assertion challenge.

### Method
POST

### Endpoint
/login/options

### Parameters
#### Request Body
- **email** (string) - Optional - The user's email address, used to locate the user for the assertion.

### Request Example
```json
{
  "email": "user@example.com"
}
```

### Response
#### Success Response (200)
- **challenge** (string) - The assertion challenge.
- **rp** (object) - Relying party information.
- **user** (object) - User information (if user is found).
- **allowCredentials** (array) - List of allowed credentials.
- **timeout** (number) - Timeout in milliseconds.
- **userVerification** (string) - User verification requirement.

#### Response Example
```json
{
  "challenge": "...",
  "rp": { "id": "example.com", "name": "Example" },
  "user": { "id": "...", "name": "user@example.com", "displayName": "User" },
  "allowCredentials": [],
  "timeout": 60000,
  "userVerification": "discouraged"
}
```
```

--------------------------------

### Register WebAuthn routes with custom paths

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Register WebAuthn routes in web.php, optionally disabling CSRF protection. The second example shows custom attestation and assertion paths.

```php
// web.php
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;
use Illuminate\Support\Facades\Route;
use Laragear\WebAuthn\Http\Routes as WebAuthnRoutes;

Route::view('welcome');

// WebAuthn Routes
WebAuthnRoutes::register()->withoutMiddleware(VerifyCsrfToken::class);
```

```php
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;
use Laragear\WebAuthn\Http\Routes as WebAuthnRoutes;

WebAuthnRoutes::register(
    attest: 'auth/register',
    assert: 'auth/login'
)->withoutMiddleware(VerifyCsrfToken::class);
```

--------------------------------

### Challenge Constructor

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/challenge.md

Creates a new Challenge instance with random or custom byte data, a timeout, verification flag, ceremony-specific properties, and an optional expiration timestamp.

```APIDOC
## Challenge Constructor

### Description
Creates a new Challenge instance with the given byte data, timeout, verification flag, ceremony-specific properties, and optional expiration timestamp.

### Method
Constructor

### Signature
```php
final public function __construct(
    public ByteBuffer $data,
    public int $timeout,
    public bool $verify = true,
    public array $properties = [],
    public int $expiresAt = 0,
)
```

### Parameters
- **$data** (\Laragear\WebAuthn\ByteBuffer) - Required - The random (or custom) challenge bytes sent to the device
- **$timeout** (int) - Required - Challenge validity in seconds
- **$verify** (bool) - Optional - Whether the user must be actively verified on response. Default: `true`
- **$properties** (array) - Optional - Ceremony-specific data. Assertion stores `credentials` (allowed credential IDs); attestation stores `user_uuid` and `user_handle`. Default: `[]`
- **$expiresAt** (int) - Optional - Unix timestamp of expiration. When `< 1`, computed as `Date::now()->getTimestamp() + $timeout` in the constructor. Default: `0`

### Behavior
All properties are promoted to public. If `$expiresAt < 1`, it is initialized to the current timestamp plus `$timeout`.
```

--------------------------------

### AttestationCreation constructor

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/attestation-ceremony.md

The AttestationCreation class is a data holder passed through the creator pipeline. Its constructor accepts parameters to configure the attestation ceremony, such as the user, challenge, user descriptor callback, resident key preference, user verification preference, JSON transport, and whether to emit excludeCredentials.

```APIDOC
## AttestationCreation constructor

### Description
Creates an AttestationCreation instance to hold data for the attestation ceremony creator pipeline.

### Method
Constructor

### Signature
```php
public function __construct(
    public ?WebAuthnAuthenticatable $user,
    public ?Challenge $challenge = null,
    public ?Closure $using = null,
    public ResidentKey $residentKey = ResidentKey::Preferred,
    public UserVerification $userVerification = UserVerification::Preferred,
    public JsonTransport $json = new JsonTransport(),
    public bool $uniqueCredentials = true,
)
```

### Parameters
- **$user** (\Laragear\WebAuthn\Contracts\WebAuthnAuthenticatable) - Required - The authenticated user creating the credential. The pipeline throws UnexpectedValueException when null.
- **$challenge** (\Laragear\WebAuthn\Challenge\Challenge) - Optional - Custom challenge; otherwise created by CreateAttestationChallenge.
- **$using** (\Closure(\Laragear\WebAuthn\Contracts\WebAuthnAuthenticatable, bool):\Laragear\WebAuthn\WebAuthnData) - Optional - Callback producing the user descriptor; defaults to $user->webAuthnData().
- **$residentKey** (\Laragear\WebAuthn\Enums\ResidentKey) - Optional - Default: ResidentKey::Preferred - Sets authenticatorSelection.residentKey.
- **$userVerification** (\Laragear\WebAuthn\Enums\UserVerification) - Optional - Default: UserVerification::Preferred - Sets authenticatorSelection.userVerification.
- **$json** (\Laragear\WebAuthn\JsonTransport) - Optional - Default: new JsonTransport() - The output JSON.
- **$uniqueCredentials** (bool) - Optional - Default: true - When false, no excludeCredentials is emitted (multi-credential devices).
```

--------------------------------

### Extract public key PEM with error handling

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/authenticator-data.md

Attempts to get the PEM public key from authenticator data, catching DataException for malformed key data and logging the error before aborting with a 422 response.

```php
use Laragear\WebAuthn\Exceptions\DataException;

try {
    $pem = $authData->getPublicKeyPem();
} catch (DataException $e) {
    logger()->error('Could not export public key: {message}', $e->getMessage());

    return response()->abort(422);
}
```

--------------------------------

### Manual Attestation Credential Saving

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/attestation-ceremony.md

Demonstrates full manual attestation including credential validation, saving, and dispatching the CredentialCreated event.

```php
// app\Http\Controllers\Auth\WebAuthnRegisterController.php
use Laragear\WebAuthn\Attestation\Validator\AttestationValidation;
use Laragear\WebAuthn\Attestation\Validator\AttestationValidator;
use Laragear\WebAuthn\Events\CredentialCreated;

public function register(Request $request, AttestationValidator $validator)
{
    $credential = $validator
        ->send(AttestationValidation::fromRequest($request, $request->user()))
        ->thenReturn()
        ->credential;

    $credential->forceFill($request->only('alias')); // optional extra attributes
    $credential->save();

    CredentialCreated::dispatch($request->user(), $credential);

    return response()->noContent();
}
```

--------------------------------

### Validate WebAuthn assertion with AssertionValidator

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/errors.md

Example of using AssertionValidator to validate a WebAuthn assertion from a request. It sends the validation, retrieves the credential, and logs in the user. On failure, it catches AssertionException and returns a JSON response with the errors.

```php
use Laragear\WebAuthn\Assertion\Validator\AssertionValidator;
use Laragear\WebAuthn\Assertion\Validator\AssertionValidation;
use Laragear\WebAuthn\Exceptions\AssertionException;

public function login(Request $request, AssertionValidator $assertion)
{
    try {
        $credential = $assertion
            ->send(AssertionValidation::fromRequest($request))
            ->thenReturn()
            ->credential;
    } catch (AssertionException $e) {
        // $e->errors() => ['assertion' => ['Assertion Error: …']]
        return response()->json(['errors' => $e->errors()], 422);
    }

    Auth::login($credential->authenticatable);
}
```

--------------------------------

### Create a challenge using the default pipeline

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/challenge.md

Uses the AssertionCreator to automatically generate and return a challenge via the default pipeline flow.

```php
use Laragear\WebAuthn\Assertion\Creator\AssertionCreation;
use Laragear\WebAuthn\Assertion\Creator\AssertionCreator;

public function challenge(Request $request, AssertionCreator $assertion)
{
    return $assertion
        ->send(new AssertionCreation($request->user()))
        ->thenReturn()
        ->json;
}
```

--------------------------------

### Modify WebAuthn model before save with AttestedRequest::save()

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Pass an array or callback to `save()` to modify the underlying WebAuthn Eloquent Model before saving. The example shows adding an alias from the request data; the commented callback is equivalent.

```php
// app\Http\Controllers\WebAuthn\WebAuthnRegisterController.php
use Laragear\WebAuthn\Http\Requests\AttestedRequest;

public function register(AttestedRequest $request)
{
    $request->validate(['alias' => 'nullable|string']);

    $attestation->save($request->only('alias'));
    
    // Same as:
    // $attestation->save(function ($credentials) use ($request) {
    //    $credentials->alias = $request->input('alias');
    // })
}
```

--------------------------------

### CborDecoder::decodePortion

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/cbor-decoder.md

Decodes a single CBOR item starting at a given byte offset and writes the offset just past the decoded item into a by-reference parameter. Useful for parsing sequential CBOR items within a larger buffer.

```APIDOC
## CborDecoder::decodePortion

### Description
Decodes a single CBOR item starting at the specified byte offset. The offset just past the decoded item is written to the by-reference parameter $endOffset, allowing sequential parsing.

### Method
static method

### Signature
public static function decodePortion(ByteBuffer|string $bufOrBin, int $startOffset, ?int &$endOffset = null): ByteBuffer|array|bool|float|int|string|null

### Parameters
- **$bufOrBin** (ByteBuffer|string) - Required - Buffer or raw binary string containing the CBOR data.
- **$startOffset** (int) - Required - Byte offset where the CBOR item begins.
- **$endOffset** (?int, by reference) - Optional - Receives the offset immediately after the decoded item. Defaults to null.

### Return Value
- **ByteBuffer|array|bool|float|int|string|null** - The decoded item.

### Exceptions
- **\Laragear\WebAuthn\Exceptions\DataException** - Thrown under the same conditions as decode().

### Example
```php
use Laragear\WebAuthn\ByteBuffer;
use Laragear\WebAuthn\CborDecoder;
use Laragear\WebAuthn\Exceptions\DataException;

try {
    $end = 0;
    $cose = CborDecoder::decodePortion($binary, $offset, $end);
    $offset = $end;
} catch (DataException $e) {
    logger()->error('Malformed COSE key: {message}', $e->getMessage());

    throw $e;
}
```
```

--------------------------------

### AttestationCreation constructor with parameters

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/attestation-ceremony.md

Defines the AttestationCreation data holder used in the attestation creator pipeline. The constructor accepts the user, optional challenge, a callback for the user descriptor, resident key and user verification preferences, a JSON transport, and a flag to control excludeCredentials emission. The user is required and the pipeline throws UnexpectedValueException when null.

```php
class AttestationCreation
{
    public function __construct(
        public ?WebAuthnAuthenticatable $user,
        public ?Challenge $challenge = null,
        public ?Closure $using = null,
        public ResidentKey $residentKey = ResidentKey::Preferred,
        public UserVerification $userVerification = UserVerification::Preferred,
        public JsonTransport $json = new JsonTransport(),
        public bool $uniqueCredentials = true,
    )
}
```

--------------------------------

### Create attestation challenge with AttestationRequest::toCreate()

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Use this controller method to create an attestation challenge for the user device. The `AttestationRequest` form request requires an authenticated user; otherwise an HTTP 403 status code is returned.

```php
// app\Http\Controllers\WebAuthn\WebAuthnRegisterController.php
use Laragear\WebAuthn\Http\Requests\AttestationRequest;

public function createChallenge(AttestationRequest $request)
{
    return $request->toCreate();
}
```

--------------------------------

### Routes::routes()

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/routes.md

Convenience wrapper that calls register() with all default parameters. Usable in route files via a use import of the static method.

```APIDOC
## Routes::routes()

### Description
Convenience wrapper that calls register() with all default parameters. Usable in route files via a use import of the static method.

### Method
N/A (static method)

### Endpoint
N/A

### Parameters
None

### Response
N/A
```

--------------------------------

### POST {assert}

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

This endpoint handles the WebAuthn assertion (login) process. It accepts a signed response from the browser, validates it, and authenticates the user if the assertion is valid.

```APIDOC
## POST {assert}

### Description
This endpoint handles the assertion (login) process for WebAuthn. It validates the signed response from the browser and authenticates the user if the assertion is valid.

### Method
POST

### Endpoint
{assert}

### Parameters
#### Request Body
- **id** (string) - Required - The credential ID echoed by the browser
- **rawId** (string) - Required - Base64url encoded credential ID
- **response.authenticatorData** (string) - Required - Base64url authenticator data
- **response.clientDataJSON** (string) - Required - Base64url client data JSON
- **response.signature** (string) - Required - Base64url signature over `SHA256(authData ‖ clientDataJSON)`
- **response.userHandle** (string) - Sometimes - Present for userless flows; must map to the credential's user UUID
- **type** (string) - Required - Must be `public-key`

#### Headers
- `X-WebAuthn-Remember` / `WebAuthn-Remember` or form field `remember` - Optional - Enable the remember-me flag for `login()`

### Request Example
```json
{
  "id": "credential-id",
  "rawId": "base64url-credential-id",
  "response": {
    "authenticatorData": "base64url-authenticator-data",
    "clientDataJSON": "base64url-client-data-json",
    "signature": "base64url-signature",
    "userHandle": "base64url-user-handle"
  },
  "type": "public-key"
}
```

### Response
#### Success Response (204)
- No content - The user authenticated successfully. The session is regenerated.

#### Error Responses
- **422 Unprocessable Entity** - Assertion failed (invalid validation steps) or credentials rejected.
- **403 Forbidden** - Only when a guard disallows the user.

#### Response Example (422)
```json
{
  "assertion": ["Assertion Error: Response challenge is not equal."]
}
```
```

--------------------------------

### AttestationCreator class pipeline configuration

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/attestation-ceremony.md

Defines the AttestationCreator, a pipeline that processes an attestation ceremony in a fixed order. The pipes array lists the sequence of operations, starting with user requirements and ending with challenge creation. This class is used to build the attestation challenge JSON.

```php
class AttestationCreator extends Pipeline
{
    protected $pipes = [
        RequireWebAuthnUser::class,
        Pipes\AddRelyingParty::class,
        Pipes\SetResidentKeyConfiguration::class,
        Pipes\MayRequireUserVerification::class,
        Pipes\AddUserDescriptor::class,
        Pipes\AddAcceptedAlgorithms::class,
        Pipes\MayPreventDuplicateCredentials::class,
        Pipes\CreateAttestationChallenge::class,
    ];
}
```

--------------------------------

### Create custom challenge with Challenge::make

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Creates a custom challenge with a 60-second expiration using a low-power random byte buffer, then passes it to the AttestationCreator pipeline. When instancing a challenge manually, set the exact expiration timestamp, not relative seconds.

```php
use FIDO\Generator;
use Laragear\WebAuthn\Attestation\Creator\AttestationCreation;
use Laragear\WebAuthn\Attestation\Creator\AttestationCreator;
use Laragear\WebAuthn\Challenge\Challenge;

public function create(Request $request, AttestationCreator $assertion)
{
    $byteBuffer = Generator::lowPowerRandom();
    
    $creation = new AttestationCreation(
        user: $request->user(),
        challenge: Challenge::make($byteBuffer, 60) 
    );

    return $assertion
        ->send($creation)
        ->thenReturn()
        ->json;
}
```

--------------------------------

### Simplified migration file for Car

Source: https://github.com/laragear/webauthn/blob/5.x/DATABASE.md

The simplified migration file published by the package. It returns the result of Car::migration() and is ready for customization.

```php
// database/migrations/2022_01_01_193000_create_cars_migration.php
use Vendor\Package\Models\Car;

return Car::migration();
```

--------------------------------

### WebAuthnData::make

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/web-authn-data.md

Static factory method to create a new WebAuthnData instance. The parameters are assigned positionally to name and displayName.

```APIDOC
## WebAuthnData::make

### Description
Static factory method to create a new WebAuthnData instance. The parameters are assigned positionally to name and displayName.

### Method
static make

### Signature
```php
public static function make(mixed $email, mixed $name): static
```

### Parameters
- **$email** (mixed) - Required - Becomes the `name` field
- **$name** (mixed) - Required - Becomes the `displayName` field

### Return
A new WebAuthnData instance.
```

--------------------------------

### AttestationObject class constructor

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/authenticator-data.md

Defines the AttestationObject with properties for authenticator data, format handler, and format name. The format is always None in this package.

```php
class AttestationObject
{
    public function __construct(
        public AuthenticatorData $authenticatorData,
        public Format $format,
        public string $formatName
    )
}
```

--------------------------------

### WebAuthnInstallCommand class declaration

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/service-provider.md

Shows the artisan command class with signature, description, and handle method. The command is hidden and publishes migrations, config, and controllers via vendor:publish.

```php
#[AsCommand('webauthn:install')]
class WebAuthnInstallCommand extends Command
{
    protected $signature = 'webauthn:install
                            {--force : Install the files even if these exist }';

    protected $description = 'Publish this package files in one command.';

    protected $hidden = true;

    public function handle(ConsoleContract $console): void
    {
        $console->call('vendor:publish', [
            '--provider' => WebAuthnServiceProvider::class,
            '--force' => $this->option('force'),
            '--tag' => ['migrations', 'config', 'controllers'],
        ]);
    }
}
```

--------------------------------

### Configure challenge bytes, timeout, and session key

Source: https://github.com/laragear/webauthn/blob/5.x/README.md

Challenge configuration: controls the number of bytes for the random challenge string, the validity timeout in seconds, and the session key used to store the challenge while being resolved.

```php
return [
    'challenge' => [
        'bytes' => 16,
        'timeout' => 60,
        'key' => '_webauthn',
    ]
];
```

--------------------------------

### routes() method implementation

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/routes.md

The routes() method is a convenience wrapper that calls register() with all default parameters. It is used to register the default WebAuthn routes.

```php
public static function routes(): void
{
    static::register();
}
```

--------------------------------

### POST {attest} — attest (register)

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/endpoints.md

Documentation for the attest (register) endpoint, including request body fields, response, and error handling.

```APIDOC
## POST {attest} — attest (register)

### Description
Registers a new WebAuthn credential for the authenticated user. Validates the attestation response and saves the credential.

### Method
POST

### Endpoint
{attest}

### Parameters
#### Request Body
- **id** (string) - Required - New credential ID
- **rawId** (string) - Required - Base64url encoded credential ID
- **response** (array) - Required - Response object
- **response.clientDataJSON** (string) - Required - Base64url client data JSON (type must be `webauthn.create`)
- **response.attestationObject** (string) - Required - Base64url CBOR attestation object (fmt must be `none`)
- **type** (string) - Required - Must be `public-key`
- **response.alias** (string) - Optional - Optional friendly name, persisted when passed to `save()` (sets `alias`)
- **response.transports** (string[]) - Optional - Transports reported by the authenticator (stored in `transports`)

### Request Example
{
  "id": "credential-id",
  "rawId": "base64url-encoded-id",
  "response": {
    "clientDataJSON": "base64url-client-data-json",
    "attestationObject": "base64url-attestation-object",
    "alias": "optional-alias",
    "transports": ["usb", "nfc"]
  },
  "type": "public-key"
}

### Response
#### Success Response (204)
No Content — credential created and saved.

#### Response Example
(No content)

### Errors
- **403** - Unauthenticated request.
- **422** - Validation failure with `attestation` error key (e.g., duplicated credential, wrong format, challenge mismatch, malformed CBOR).

#### Error Example
{
  "attestation": ["Attestation Error: Credential ID already exists in the database."]
}
```

--------------------------------

### Challenge::random()

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/challenge.md

Creates a new Challenge with random byte data.

```APIDOC
## Challenge::random()

### Description
Creates a new Challenge with random byte data.

### Method
`random()` (static)

### Signature
```php
public static function random(int $length, int $timeout, bool $verify = true, array $options = []): static
```

### Parameters
- **$length** (int) - Required - Length of the random byte data
- **$timeout** (int) - Required - Challenge validity in seconds
- **$verify** (bool) - Optional - Whether the user must be actively verified. Default: `true`
- **$options** (array) - Optional - Ceremony-specific properties. Default: `[]`

### Return Value
- **static** - A new Challenge instance created via `new static(ByteBuffer::makeRandom($length), $timeout, $verify, $options)`.
```

--------------------------------

### Build challenge response with JsonTransport

Source: https://github.com/laragear/webauthn/blob/5.x/_autodocs/api-reference/json-transport.md

Creates a JsonTransport, sets dot-notation keys for rp.name, challenge, timeout, and userVerification, then returns an HTTP JSON response via toResponse().

```php
use Laragear\WebAuthn\JsonTransport;

$json = new JsonTransport();

$json->set('rp.name', 'SecureBank');
$json->set('challenge', $challenge->data->toBase64Url());
$json->set('timeout', 60000);
$json->set('userVerification', 'required');

return $json->toResponse($request);
```
Tokens:
Raw