Passkey

# Brok UI: Passkey (`passkey`)

A backend-agnostic WebAuthn ceremony: sign in with or add a passkey against your own options and verify endpoints, or laravel/passkeys through a preset, with clear pending, unsupported, cancelled, error and success states.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add passkey
```

## Usage

```blade
{{-- Sign in with a passkey. Point the URLs at your WebAuthn endpoints. The
     docs site answers these URLs with demo endpoints that keep no accounts:
     the browser prompt is real, and verification always explains why it
     cannot sign you in. --}}
<div class="w-full max-w-xs">
    <x-ui.passkey options-url="/passkeys/login/options" verify-url="/passkeys/login" redirect="/dashboard" />
</div>
```

## Props

- `mode` (authenticate|register, default `authenticate`) — authenticate calls navigator.credentials.get() to sign in; register calls navigator.credentials.create() to add a passkey.
- `optionsUrl` (string, default ``) — Endpoint that returns WebAuthn JSON options (under optionsKey, publicKey or at the top level). A POST in register mode sends { name }. Empty uses the preset route.
- `verifyUrl` (string, default ``) — POST endpoint that receives the credential JSON (under credentialKey when set, with the body fields; register mode adds name) and verifies it. A JSON redirect in the response is followed. Empty uses the preset route.
- `redirect` (string|null, default `null`) — Where to go after success when the response has no redirect.
- `reload` (bool, default `false`) — Reload the page after success when there is no redirect, so a list shows the new passkey.
- `requireName` (bool, default `true`) — Register mode: refuse to start until the bound name field has a value.
- `label` (string|null, default `null`) — Label of the default button: 'Sign in with a passkey' or 'Add passkey'.
- `preset` (string|null, default `null`) — A known backend contract. 'laravel-passkeys' sets optionsMethod GET, optionsKey options, credentialKey credential and the laravel/passkeys routes for the mode (/passkeys/login/options and /passkeys/login, or /user/passkeys/options and /user/passkeys). Explicit props win.
- `optionsMethod` (GET|POST|null, default `null`) — HTTP method of the options request. Null uses the preset, else POST. GET sends no body.
- `optionsKey` (string|null, default `null`) — Response key that wraps the options, for example options. Null uses the preset, else publicKey or the top-level object.
- `credentialKey` (string|null, default `null`) — Verify body field that holds the credential, for example credential. Null uses the preset, else the credential is the body.
- `body` (array, default `[]`) — Extra verify body fields, for example ['remember' => true]. Bind them to fields in the slot with x-model="extra.<field>".
- `type` (string, default `button`) — Declared by @props in the registry Blade source.
- `variant` (string, default `default`) — Declared by @props in the registry Blade source.

## Use when

- Use when users must enter freeform information that cannot be reliably selected from a list.
- Sign-in or security settings offer passkeys and the server already exposes WebAuthn options and verify endpoints (laravel/passkeys with preset="laravel-passkeys", another PHP package or your own code).
- You need the browser ceremony with honest states for unsupported browsers, a dismissed prompt and server errors.

## Avoid when

- Do not choose a freeform field when a constrained choice would reduce errors or cognitive load.
- The server has no WebAuthn endpoints yet; the component only runs the browser side.
- A one-time code is the second factor; use input-otp in auth-two-factor.

## Anti-patterns

- Using freeform entry for a bounded answer set

## Rules

- Use the `<brok:passkey>` tag (or `<x-ui.passkey>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/passkey
- Registry JSON (files, props, contract): https://brokui.dev/r/open/passkey.json

{{--
    Passkey: runs a WebAuthn ceremony against your own endpoints, with no
    dependency on a PHP package. `mode="authenticate"` signs in,
    `mode="register"` adds a passkey. The server returns WebAuthn JSON options
    from `optionsUrl` and verifies the credential posted to `verifyUrl`.

    The request shape is configurable, so no app-side adapter is needed:
    `optionsMethod` (POST or GET), `optionsKey` (the key that wraps the options
    in the response), `credentialKey` (the field that wraps the credential in
    the verify body) and `body` (extra verify fields). `preset="laravel-passkeys"`
    sets all three and the laravel/passkeys routes; explicit props still win.

    With an empty slot it renders its button and status line. Compose your own
    layout with <x-ui.passkey.button> and <x-ui.passkey.status> inside the slot;
    in register mode bind a name field with x-model="name", and bind extra body
    fields with x-model="extra.<field>" (for example extra.remember).
--}}
@props([
    'mode' => 'authenticate',
    'optionsUrl' => '',
    'verifyUrl' => '',
    // Where to go after success. A `redirect` in the verify response wins.
    'redirect' => null,
    // Reload the page after success when there is no redirect (a list that
    // shows the new passkey).
    'reload' => false,
    // Register mode: refuse to start until the name field has a value.
    'requireName' => true,
    'label' => null,
    // A known backend contract: null or 'laravel-passkeys'.
    'preset' => null,
    // GET or POST for the options request. Null: the preset, else POST.
    'optionsMethod' => null,
    // The response key that wraps the options, for example 'options'. Null:
    // the preset, else `publicKey` or the top-level object.
    'optionsKey' => null,
    // The verify body field that holds the credential, for example
    // 'credential'. Null: the preset, else the credential is the body.
    'credentialKey' => null,
    // Extra fields for the verify body, for example ['remember' => true].
    'body' => [],
])

@php
    $mode = $mode === 'register' ? 'register' : 'authenticate';
    $label ??= $mode === 'register' ? 'Add passkey' : 'Sign in with a passkey';
    $contract = [
        'laravel-passkeys' => [
            'optionsMethod' => 'GET',
            'optionsKey' => 'options',
            'credentialKey' => 'credential',
            'authenticate' => ['/passkeys/login/options', '/passkeys/login'],
            'register' => ['/user/passkeys/options', '/user/passkeys'],
        ],
    ][$preset] ?? [];
    $optionsMethod = strtoupper((string) ($optionsMethod ?? $contract['optionsMethod'] ?? 'POST')) === 'GET' ? 'GET' : 'POST';
    $config = [
        'mode' => $mode,
        'optionsUrl' => (string) (filled($optionsUrl) ? $optionsUrl : ($contract[$mode][0] ?? '')),
        'verifyUrl' => (string) (filled($verifyUrl) ? $verifyUrl : ($contract[$mode][1] ?? '')),
        'optionsMethod' => $optionsMethod,
        'optionsKey' => $optionsKey ?? $contract['optionsKey'] ?? null,
        'credentialKey' => $credentialKey ?? $contract['credentialKey'] ?? null,
        'body' => (object) (array) $body,
        'redirect' => $redirect,
        'reload' => (bool) $reload,
        'requireName' => (bool) $requireName,
        'csrf' => csrf_token(),
        'messages' => [
            'unsupported' => __('This browser does not support passkeys. Use another way to continue.'),
            'pending' => $mode === 'register' ? __('Follow the prompt from your browser to create the passkey.') : __('Follow the prompt from your browser to use your passkey.'),
            'cancelled' => __('The passkey request was cancelled or timed out. Try again when you are ready.'),
            'success' => $mode === 'register' ? __('Passkey added.') : __('Signed in.'),
            'error' => __('Something went wrong with the passkey. Try again.'),
            'duplicate' => __('This device already has a passkey for your account.'),
            'notAvailable' => __('Passkeys are not available on this site or device.'),
            'nameRequired' => __('Enter a name for the passkey.'),
        ],
    ];
@endphp

<div
    data-slot="passkey"
    data-mode="{{ $mode }}"
    x-data="uiPasskey(@js($config))"
    x-bind:data-state="state"
    {{ $attributes->merge(['class' => 'flex min-w-0 flex-col gap-2']) }}
>
    @if ($slot->isEmpty())
        <x-ui.passkey.button>{{ __($label) }}</x-ui.passkey.button>
        <x-ui.passkey.status />
    @else
        {{ $slot }}
    @endif
    <noscript>
        <p class="text-sm text-muted-foreground">{{ __('Passkeys need JavaScript. Use another way to continue.') }}</p>
    </noscript>
</div>

{{--
    Starts the ceremony of the surrounding <x-ui.passkey>. As type="submit"
    inside a form, the form's submit (x-on:submit.prevent="start()") starts it
    instead, so native `required` validation runs first. Disabled while a
    request runs and when the browser has no passkey support.
--}}
@props([
    'type' => 'button',
    'variant' => 'default',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
@endphp

<x-ui.button
    :type="$type === 'submit' ? 'submit' : 'button'"
    :variant="$variant"
    x-bind:disabled="busy || unsupported"
    x-bind:aria-busy="busy ? 'true' : null"
    x-on:click="$el.type === 'submit' || start()"
    {{ $attributes->merge(['class' => 'w-full']) }}
>
    <x-slot:icon>
        <svg x-show="!busy" class="size-4 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="8" cy="15" r="4" /><path d="m10.85 12.15 7.65-7.65M18 5l2 2M15 8l2 2" /></svg>
        {{-- The button's own loading spinner, shown while the ceremony runs. --}}
        <svg x-show="busy" x-cloak data-slot="passkey-spinner" class="size-4 shrink-0 animate-spin motion-reduce:animate-none" viewBox="0 0 24 24" fill="none" aria-hidden="true">
            <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
            <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z"></path>
        </svg>
    </x-slot:icon>
    {{ $slot }}
</x-ui.button>

/**
 * Passkey (WebAuthn) ceremony, backend-agnostic.
 *
 * 1. POST (or GET, `optionsMethod`) `optionsUrl` → the server returns
 *    PublicKeyCredential request (sign in) or creation (register) options in
 *    the WebAuthn JSON form: under `optionsKey` when set, else under
 *    `publicKey` or at the top level.
 * 2. navigator.credentials.get()/create() runs the browser ceremony.
 * 3. POST `verifyUrl` with the credential as JSON, under `credentialKey` when
 *    set, merged with the `extra` fields (registration adds `name`).
 *    A JSON response may carry `redirect`; otherwise `redirect`/`reload` from
 *    the config apply, and `passkey-success` is dispatched either way.
 *
 * States: idle, unsupported, pending, cancelled, error, success. `message`
 * holds the text for the current state; the Blade status region reads it.
 */

function toBytes(value) {
    const base64 = String(value).replace(/-/g, '+').replace(/_/g, '/');
    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
    const binary = atob(padded);
    const bytes = new Uint8Array(binary.length);
    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);

    return bytes.buffer;
}

function isBinary(value) {
    return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
}

function toBase64Url(buffer) {
    if (!buffer) return null;
    const bytes = ArrayBuffer.isView(buffer)
        ? new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
        : new Uint8Array(buffer);
    let binary = '';
    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);

    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

function withIds(list) {
    return Array.isArray(list) ? list.map((item) => ({ ...item, id: toBytes(item.id) })) : list;
}

function prfValues(values) {
    if (!values || typeof values !== 'object') return values;

    return {
        ...values,
        first: toBytes(values.first),
        ...(values.second != null ? { second: toBytes(values.second) } : {}),
    };
}

/**
 * Client extension inputs from JSON: the binary members the WebAuthn JSON
 * form carries as base64url (prf, largeBlob.write, credBlob) become bytes.
 */
function parseExtensions(extensions) {
    if (!extensions || typeof extensions !== 'object') return extensions;
    const parsed = { ...extensions };
    if (extensions.prf && typeof extensions.prf === 'object') {
        const prf = { ...extensions.prf };
        if (prf.eval) prf.eval = prfValues(prf.eval);
        if (prf.evalByCredential && typeof prf.evalByCredential === 'object') {
            prf.evalByCredential = Object.fromEntries(
                Object.entries(prf.evalByCredential).map(([id, values]) => [id, prfValues(values)]),
            );
        }
        parsed.prf = prf;
    }
    if (extensions.largeBlob && typeof extensions.largeBlob.write === 'string') {
        parsed.largeBlob = { ...extensions.largeBlob, write: toBytes(extensions.largeBlob.write) };
    }
    if (typeof extensions.credBlob === 'string') parsed.credBlob = toBytes(extensions.credBlob);

    return parsed;
}

/** Client extension outputs to JSON: every binary value becomes base64url. */
function serializeExtensionResults(value) {
    if (isBinary(value)) return toBase64Url(value);
    if (Array.isArray(value)) return value.map(serializeExtensionResults);
    if (value && typeof value === 'object') {
        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, serializeExtensionResults(item)]));
    }

    return value;
}

function parseOptions(json, mode) {
    const options = json?.publicKey ?? json;
    if (mode === 'register') {
        if (typeof PublicKeyCredential.parseCreationOptionsFromJSON === 'function') {
            return PublicKeyCredential.parseCreationOptionsFromJSON(options);
        }

        return {
            ...options,
            challenge: toBytes(options.challenge),
            user: { ...options.user, id: toBytes(options.user.id) },
            excludeCredentials: withIds(options.excludeCredentials),
            ...(options.extensions ? { extensions: parseExtensions(options.extensions) } : {}),
        };
    }
    if (typeof PublicKeyCredential.parseRequestOptionsFromJSON === 'function') {
        return PublicKeyCredential.parseRequestOptionsFromJSON(options);
    }

    return {
        ...options,
        challenge: toBytes(options.challenge),
        allowCredentials: withIds(options.allowCredentials),
        ...(options.extensions ? { extensions: parseExtensions(options.extensions) } : {}),
    };
}

function serialize(credential) {
    if (typeof credential.toJSON === 'function') return credential.toJSON();
    const response = credential.response;

    return {
        id: credential.id,
        rawId: toBase64Url(credential.rawId),
        type: credential.type,
        authenticatorAttachment: credential.authenticatorAttachment ?? null,
        clientExtensionResults: serializeExtensionResults(credential.getClientExtensionResults?.() ?? {}),
        response: {
            clientDataJSON: toBase64Url(response.clientDataJSON),
            ...(response.attestationObject ? {
                attestationObject: toBase64Url(response.attestationObject),
                transports: response.getTransports?.() ?? [],
            } : {
                authenticatorData: toBase64Url(response.authenticatorData),
                signature: toBase64Url(response.signature),
                userHandle: toBase64Url(response.userHandle),
            }),
        },
    };
}

class ServerError extends Error {}

document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiPasskey', (config = {}) => ({
        mode: config.mode === 'register' ? 'register' : 'authenticate',
        state: 'idle',
        message: '',
        name: '',
        // Extra verify body fields; bind with x-model="extra.remember".
        extra: { ...(config.body ?? {}) },
        controller: null,

        get busy() {
            return this.state === 'pending';
        },

        get unsupported() {
            return this.state === 'unsupported';
        },

        init() {
            if (!window.PublicKeyCredential || !navigator.credentials) {
                this.state = 'unsupported';
                this.message = config.messages?.unsupported ?? '';
            }
        },

        // Removed from the page (Livewire morph, navigation): stop the
        // ceremony and both requests, and never act on a late response.
        destroy() {
            this.controller?.abort();
            this.controller = null;
        },

        /** Stop a running ceremony; its late results are ignored. */
        cancel() {
            if (!this.controller) return;
            this.controller.abort();
            this.controller = null;
            this.setState('cancelled');
        },

        setState(state, message = null) {
            this.state = state;
            this.message = message ?? config.messages?.[state] ?? '';
        },

        async request(url, body, signal, method = 'POST') {
            const get = method === 'GET';
            const response = await fetch(url, {
                method,
                credentials: 'same-origin',
                signal,
                headers: {
                    ...(get ? {} : { 'Content-Type': 'application/json' }),
                    Accept: 'application/json',
                    'X-Requested-With': 'XMLHttpRequest',
                    ...(config.csrf ? { 'X-CSRF-TOKEN': config.csrf } : {}),
                },
                ...(get ? {} : { body: JSON.stringify(body) }),
            });
            const json = await response.json().catch(() => null);
            if (!response.ok) {
                // Laravel validation errors: the first field message, else `message`.
                const first = json?.errors ? Object.values(json.errors).flat()[0] : null;
                throw new ServerError(first ?? json?.message ?? '');
            }

            return json ?? {};
        },

        async start() {
            if (this.busy || this.unsupported) return;
            if (this.mode === 'register' && this.name.trim() === '' && config.requireName) {
                this.setState('error', config.messages?.nameRequired);

                return;
            }

            this.setState('pending');
            this.controller?.abort();
            // One signal for this ceremony: the options request, the browser
            // prompt and the verify request. Once it aborts (destroy() or
            // cancel()), nothing below may change state, dispatch or navigate.
            const controller = new AbortController();
            const { signal } = controller;
            this.controller = controller;

            try {
                const named = this.mode === 'register' ? { name: this.name.trim() } : {};
                const response = await this.request(config.optionsUrl, named, signal, config.optionsMethod);
                const options = parseOptions(config.optionsKey ? response?.[config.optionsKey] : response, this.mode);
                if (signal.aborted) return;
                const credential = this.mode === 'register'
                    ? await navigator.credentials.create({ publicKey: options, signal })
                    : await navigator.credentials.get({ publicKey: options, signal });
                if (signal.aborted) return;
                if (!credential) {
                    this.setState('cancelled');

                    return;
                }

                const payload = serialize(credential);
                const credentialBody = config.credentialKey ? { [config.credentialKey]: payload } : payload;
                const result = await this.request(config.verifyUrl, { ...this.extra, ...credentialBody, ...named }, signal);
                if (signal.aborted) return;

                this.setState('success');
                this.$dispatch('passkey-success', { mode: this.mode, response: result });
                const redirect = result.redirect ?? config.redirect;
                if (redirect) window.location.assign(redirect);
                else if (config.reload) window.location.reload();
                else if (this.mode === 'register') this.name = '';
            } catch (error) {
                if (!signal.aborted) this.fail(error);
            } finally {
                if (this.controller === controller) this.controller = null;
            }
        },

        fail(error) {
            const messages = config.messages ?? {};
            if (error instanceof ServerError) {
                this.setState('error', error.message || messages.error);
            } else if (error?.name === 'NotAllowedError' || error?.name === 'AbortError') {
                // The user dismissed the prompt, or it timed out.
                this.setState('cancelled');
            } else if (error?.name === 'InvalidStateError' && this.mode === 'register') {
                this.setState('error', messages.duplicate);
            } else if (error?.name === 'SecurityError' || error?.name === 'NotSupportedError') {
                this.setState('error', messages.notAvailable);
            } else {
                this.setState('error', messages.error);
            }
            this.$dispatch('passkey-error', { mode: this.mode, state: this.state, name: error?.name ?? null });
        },
    }));
});