MVP: Add WebAuthn passkey authentication support

[heyvaleria]

Before this PR, Clearance's only authentication path was email and password.
There was no built-in support for WebAuthn passkeys, so apps that wanted passkey sign-in had to build the entire ceremony layer themselves, managing credential options, challenge storage, assertion verification, and session sign-in completely outside of Clearance.

The goal of this code change was to add passkey support as an opt-in feature: run a generator to prepare the database and User model, configure the webauthn gem for the host app that uses clearance, and get a working JSON backend for both the registration and authentication ceremonies, integrated with Clearance's existing sign_in guard stack.

Clearance::Passkey is a new ActiveRecord model that belongs to a user and stores the credential's external_id (the ID issued by the authenticator), public_key, sign_count, and a human-readable label. external_id is validated for uniqueness so the same credential can't be registered twice.
The clearance:passkeys generator sets up everything the host app needs: it creates an add_webauthn_id_to_users migration (skipped if the column already exists) and a create_passkeys migration (skipped if the table already exists), injects has_many :passkeys into the User model, and prints a README with instructions for configuring the webauthn gem.

PasskeysController handles the registration ceremony.
GET /passkeys/new returns WebAuthn credential creation options as JSON and stores the challenge in the session; the user's webauthn_id is generated lazily at this point if not already set.
POST /passkeys verifies the credential response and persists the new passkey against the current user.
Registration requires the user to be signed in.

PasskeyAuthenticationsController handles the authentication ceremony.
GET /passkey_authentication/new returns assertion options as JSON.
POST /passkey_authentication verifies the assertion, updates the stored sign count, and delegates to Clearance's sign_in so the full guard stack still runs.
On success it responds with JSON containing a redirect_to key pointing to Clearance.configuration.redirect_url.

Both controllers render JSON, since the WebAuthn API is driven by browser-side JavaScript.
Routes for both are added inside the existing routes_enabled? block.

In a flexible thoughbot approach, I decided that the WebAuthn configuration (origin, rp_name) is deliberately left to the host app via WebAuthn.configure rather than threading it through Clearance.configuration — the webauthn gem already provides the right home for those settings.

Setup instructions

1) Install

bundle add clearance
rails generate clearance:install   # skip if already using Clearance                                                                
rails generate clearance:passkeys
rails db:migrate

By running bundle add clearance, webauthn ~> 3.0 comes as a dependency.

2) Configure WebAuthn

Create config/initializers/webauthn.rb

  WebAuthn.configure do |config|                                                                                                      
    config.origin = "https://yourapp.example.com"  # "http://localhost:3000" in dev
    config.rp_name = "Your App Name"                                                                                                  
  end

3) Endpoints

4) Registration flow (user must be signed in)

1. Fetch creation options from Clearance

  const options = await fetch("/passkeys/new").then(r => r.json()) 

3. Prompt the browser to create a credential

  const credential = await navigator.credentials.create({ publicKey: options })

4. POST the result back, including a human-readable label

  await fetch("/passkeys", {
    method: "POST",                                                                                                                   
    headers: { "Content-Type": "application/json", "X-CSRF-Token": csrfToken },
    body: JSON.stringify({ ...credential, label: "My MacBook" })                                                                      
  })

5) Authentication flow

1. Fetch assertion options

  const options = await fetch("/passkey_authentication/new").then(r => r.json())

2. Prompt the browser to sign with a passkey

  const credential = await navigator.credentials.get({ publicKey: options })             

3. POST the result — on success, response body has { redirect_to: "/dashboard" }

  const result = await fetch("/passkey_authentication", {
    method: "POST",                                                                                                                   
    headers: { "Content-Type": "application/json", "X-CSRF-Token": csrfToken },
    body: JSON.stringify(credential)                                                                                                  
  }).then(r => r.json())                                                                                                              
  
  window.location = result.redirect_to       

The WebAuthn browser API expects specific object shapes — for a production app you'd typically reach for a library like @github/webauthn-json to handle the Base64url encoding/decoding between the JSON and the native credential objects.

[FerPerales]

@heyvaleria looks good! I'll do some testing during upcoming investment time. Shall we release this as a new beta version so you can add more features to make it production ready?