webauthn-rails 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c23bb425dcafa1c050ddda0f7533a264ea071451215000d54da251c712a5189c
-  data.tar.gz: fa31284ff35f0804a31ef43eeb5e0905407581b197e4ba331ad52a26f33a775e
+  metadata.gz: 5bf8803deeac8d925eef701fa4b9a25b3ecea1288e5af2b07dad81e60b16574d
+  data.tar.gz: ad28b85f03d4d693ec12d94c6702e6a8a6a0fbdd9226303efa520e61bc6c1000
 SHA512:
-  metadata.gz: 7e67df5d493f1d58d9567198be453b130a4ce7f6a0bdfb8ef98227bfec80255d79fbb42d8eb11656f30f1a7a0dc2f6693f027fa4160e9ceec02aabafd87a833a
-  data.tar.gz: 4b57092b8e648edd83f61b74801d4c134e74c94c7caf63dd1bf0988c50bdc564a450f44e0ddb4a8fdb578162683997c4c2e42f54500faedfdf2c068d3854b544
+  metadata.gz: 7d10d95538f98bfd0375159c3bd7acba311992cf06062aecfae5fe1f1c4bdf57de6494fd6c5ade9e70a5d5e096be723a768d330ec3722fe1f659904f4842d834
+  data.tar.gz: c81deb6084edc784f72d1cda4189e651a4748a75af71d80ad15e942a4ca6bd497f5f3211930b3416bb0ea474577fe7481850226938a9b725d1933bcbec652031

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Cedarcode
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,32 +1,186 @@
-# Webauthn::Rails
+# WebAuthn Rails
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/webauthn/rails`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/webauthn-rails.svg)](https://badge.fury.io/rb/webauthn-rails)
 
-## Installation
+**webauthn-rails** adds passkeys to your Rails app with almost no setup. It provides a generator that installs everything you need for a secure passwordless and two-factor authentication flow, built on top of the [Rails Authentication system](https://guides.rubyonrails.org/security.html). Webauthn Rails combines [Stimulus](https://stimulus.hotwired.dev/) for the frontend experience with the [WebAuthn Ruby gem](https://github.com/cedarcode/webauthn-ruby) on the server side – giving you a ready-to-use authentication system.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Requirements
 
-Install the gem and add to the application's Gemfile by executing:
+- **Ruby**: 3.2+
+- **Rails**: 8.0+
+- **Stimulus Rails**: This gem requires [stimulus-rails](https://github.com/hotwired/stimulus-rails) to be installed and configured in your application
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+### JavaScript Dependencies
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+The generator automatically handles JavaScript dependencies based on your setup:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+- **Importmap**: Pins `@github/webauthn-json/browser-ponyfill` to your importmap
+- **Node.js/Yarn/Bun**: Adds the package to your package manager
 
 ## Usage
 
-TODO: Write usage instructions here
+Install the gem by running:
 
-## Development
+```bash
+$ bundle add webauthn-rails --group development
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Next, you need to run the generator:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+$ bin/rails generate webauthn_authentication
+```
+
+If you haven't generated Rails authentication yet, you can pass the `--with-rails-authentication` flag in order to generate it alongside the webauthn authentication:
+```bash
+$ bin/rails generate webauthn_authentication --with-rails-authentication
+```
+
+This generator will:
+
+- **Optionally** invoke the [Rails Authentication generator](https://github.com/rails/rails/blob/main/railties/lib/rails/generators/rails/authentication/authentication_generator.rb) if the `--with-rails-authentication` flag is passed.
+- Modifies the `SessionsController` to support WebAuthn two-factor authentication.
+- Create controllers for handling passwordless and two-factor authentication, as well as credential management.
+- Update new session views to support passkey authentication.
+- Add views for credential management and two-factor authentication.
+- Update the `User` model to include association with credentials and webauthn-related logic.
+- Generate database migrations for WebAuthn credentials.
+- Add passkey authentication, two-factor authentication and credential management routes.
+- Generate a Stimulus controller for WebAuthn interactions.
+- Create the WebAuthn initializer.
+
+### Post-Installation Configuration
+
+After running the generator, you **must** configure the WebAuthn settings:
+
+1. Edit `config/initializers/webauthn.rb` and set your allowed origins and Relying Party name:
+
+```ruby
+WebAuthn.configure do |config|
+  # This value needs to match `window.location.origin` evaluated by
+  # the User Agent during registration and authentication ceremonies.
+  config.allowed_origins = ["https://yourapp.com"]
+
+  # Relying Party name for display purposes
+  config.rp_name = "Your App Name"
+end
+```
+
+2. Run the migrations:
+
+```bash
+$ bin/rails db:migrate
+```
+
+## How it Works
+
+### User Sign-In
+
+Users can sign in by visiting `/session/new`. The generated setup supports two ways to log in:
+
+- Email and password – via the standard Rails Authentication flow. On top of that, if the user has enabled two-factor authentication, they will be prompted to verify with a WebAuthn credential.
+- Passkey (WebAuthn) – by selecting a [passkey](https://www.w3.org/TR/webauthn-3/#discoverable-credential) linked to the user’s account.
+
+The WebAuthn passkey sign-in flow works as follows:
+1. User clicks "Sign in with Passkey", starting a WebAuthn authentication ceremony.
+2. Browser shows available passkeys.
+3. User selects a passkey and verifies with their [authenticator](https://www.w3.org/TR/webauthn-3/#webauthn-authenticator).
+4. The server verifies the response and signs in the user.
+
+The WebAuthn two-factor authentication flow works as follows:
+1. User signs in with email and password.
+2. If the user has 2FA enabled, they are asked to use a webauthn credential to complete sign-in.
+3. User selects a credential and verifies with their authenticator.
+4. The server verifies the response and completes sign-in.
+
+### Adding Credentials
+
+Signed-in users can add passkeys by visiting `/passkeys/new`, and second factor credentials by visiting `/second_factor_webauthn_credentials/new`.
+
+
+### Models
+
+#### User Model
+
+The generator adds WebAuthn functionality to your User model:
+
+```ruby
+class User < ApplicationRecord
+  has_many :webauthn_credentials, dependent: :destroy
+  with_options class_name: "WebauthnCredential" do
+    has_many :second_factor_webauthn_credentials, -> { second_factor }
+    has_many :passkeys, -> { passkey }
+  end
+
+  after_initialize do
+    self.webauthn_id ||= WebAuthn.generate_user_id
+  end
+
+  def second_factor_enabled?
+    webauthn_credentials.any?
+  end
+end
+```
+
+#### WebauthnCredential Model
+
+Stores the public keys and metadata for each registered authenticator:
+
+```ruby
+class WebauthnCredential < ApplicationRecord
+  belongs_to :user
+
+  validates :external_id, :public_key, :nickname, :sign_count, presence: true
+  validates :external_id, uniqueness: true
+  validates :sign_count,
+    numericality: { only_integer: true, greater_than_or_equal_to: 0, less_than_or_equal_to: 2**32 - 1 }
+
+  enum :authentication_factor, { first_factor: 0, second_factor: 1 }
+
+  scope :passkey, -> { first_factor }
+end
+```
+
+## Customization
+
+### Views
+
+The generator creates view templates that you can customize:
+
+- `app/views/passkeys/new.html.erb` - Add new passkey form.
+- `app/views/second_factor_webauthn_credentials/new.html.erb` - Add new second factor credential form.
+- `app/views/second_factor_authentications/new.html.erb` - Two-factor authentication form.
+
+### Stimulus Controller
+
+The generated Stimulus controller (`webauthn_credentials_controller.js`) handles the WebAuthn JavaScript API interactions. You can extend or customize it for your specific needs.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/webauthn-rails.
+Issues and pull requests are welcome on GitHub at https://github.com/cedarcode/webauthn-rails.
+
+### Development
+
+After checking out the repo, run:
+
+```bash
+$ bundle install
+```
+
+To run the tests:
+
+```bash
+$ bundle exec rake test
+$ bundle exec rake test_dummy
+```
+
+To run the linter:
+
+```bash
+$ bundle exec rubocop
+```
+
+Before submitting a PR, make sure both tests pass and there are no linting errors.
 
 ## License
 

data/Rakefile

@@ -1,8 +1,16 @@
-# frozen_string_literal: true
+require "bundler/setup"
+require 'rake/testtask'
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb'].exclude('test/tmp/**/*_test.rb').exclude('test/dummy/**/*_test.rb')
+end
 
-task default: :spec
+Rake::TestTask.new(:test_dummy) do |t|
+  t.libs << 'test/dummy/lib'
+  t.libs << 'test/dummy/test'
+  t.test_files = FileList['test/dummy/**/*_test.rb']
+end

data/lib/generators/erb/webauthn_authentication/templates/app/views/passkeys/new.html.erb.tt

@@ -0,0 +1,18 @@
+<%%= tag.div(flash[:alert], style: "color:red") if flash[:alert] %>
+<%%= tag.div(flash[:notice], style: "color:green") if flash[:notice] %>
+
+<%%= form_with(
+  scope: :credential,
+  url: passkeys_path,
+  data: {
+    controller: "webauthn-credentials",
+    action: "webauthn-credentials#create:prevent",
+    "webauthn-credentials-options-url-value": create_options_passkeys_path,
+  }) do |form| %>
+  <div class="field">
+    <%%= form.label :nickname, 'Security Key nickname' %>
+    <%%= form.text_field :nickname, required: true %>
+  </div>
+  <%%= form.hidden_field :public_key_credential, data: { "webauthn-credentials-target": "credentialHiddenInput" } %>
+  <%%= form.submit "Add Security Key", disabled: true, data: { "webauthn-credentials-target": "submitButton" } %>
+<%% end %>

data/lib/generators/erb/webauthn_authentication/templates/app/views/second_factor_authentications/new.html.erb.tt

@@ -0,0 +1,18 @@
+<%%= tag.div(flash[:alert], style: "color:red") if flash[:alert] %>
+<%%= tag.div(flash[:notice], style: "color:green") if flash[:notice] %>
+
+<h3>Two-factor authentication</h3>
+<p>Use a security key to sign in.</p>
+
+<%%= form_with(
+  scope: :session,
+  url: second_factor_authentication_path,
+  method: :post,
+  data: {
+    controller: "webauthn-credentials",
+    action: "webauthn-credentials#get:prevent",
+    "webauthn-credentials-options-url-value": get_options_second_factor_authentication_path,
+  }) do |f| %>
+    <%%= f.hidden_field :public_key_credential, data: { "webauthn-credentials-target": "credentialHiddenInput" } %>
+    <%%= f.submit "Use Security Key", disabled: true, data: { "webauthn-credentials-target": "submitButton" } %>
+<%% end %>

data/lib/generators/erb/webauthn_authentication/templates/app/views/second_factor_webauthn_credentials/new.html.erb.tt

@@ -0,0 +1,18 @@
+<%%= tag.div(flash[:alert], style: "color:red") if flash[:alert] %>
+<%%= tag.div(flash[:notice], style: "color:green") if flash[:notice] %>
+
+<%%= form_with(
+  scope: :credential,
+  url: second_factor_webauthn_credentials_path,
+  data: {
+    controller: "webauthn-credentials",
+    action: "webauthn-credentials#create:prevent",
+    "webauthn-credentials-options-url-value": create_options_second_factor_webauthn_credentials_path,
+  }) do |form| %>
+  <div class="field">
+    <%%= form.label :nickname, 'Security Key nickname' %>
+    <%%= form.text_field :nickname, required: true %>
+  </div>
+  <%%= form.hidden_field :public_key_credential, data: { "webauthn-credentials-target": "credentialHiddenInput" } %>
+  <%%= form.submit "Add Security Key", disabled: true, data: { "webauthn-credentials-target": "submitButton" } %>
+<%% end %>

data/lib/generators/erb/webauthn_authentication/webauthn_authentication_generator.rb

@@ -0,0 +1,35 @@
+require "rails/generators/erb"
+
+module Erb
+  module Generators
+    class WebauthnAuthenticationGenerator < Rails::Generators::Base
+      hide!
+      source_root File.expand_path("../templates", __FILE__)
+
+      def create_files
+        template "app/views/passkeys/new.html.erb.tt"
+        template "app/views/second_factor_authentications/new.html.erb.tt"
+        template "app/views/second_factor_webauthn_credentials/new.html.erb.tt"
+      end
+
+      def inject_into_rails_session_view
+        append_to_file "app/views/sessions/new.html.erb" do
+          <<-ERB.strip_heredoc
+            <%= form_with(
+              scope: :session,
+              url: webauthn_session_path,
+              method: :post,
+              data: {
+                controller: "webauthn-credentials",
+                action: "webauthn-credentials#get:prevent",
+                "webauthn-credentials-options-url-value": get_options_webauthn_session_path,
+              }) do |f| %>
+                <%= f.hidden_field :public_key_credential, data: { "webauthn-credentials-target": "credentialHiddenInput" } %>
+                <%= f.submit "Sign In with Passkey", disabled: true, data: { "webauthn-credentials-target": "submitButton" } %>
+            <% end %>
+          ERB
+        end
+      end
+    end
+  end
+end

data/lib/generators/test_unit/webauthn_authentication/templates/test/controllers/passkeys_controller_test.rb

@@ -0,0 +1,111 @@
+require "test_helper"
+require "webauthn/fake_client"
+
+class PasskeysControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+    @client = WebAuthn::FakeClient.new(WebAuthn.configuration.allowed_origins.first)
+  end
+
+  test "initiates Passkey creation when user is authenticated" do
+    sign_in_as @user
+    post create_options_passkeys_url
+
+    assert_response :success
+    body = JSON.parse(response.body)
+    assert body["challenge"].present?
+    assert body["authenticatorSelection"]["residentKey"] == "required"
+    assert body["authenticatorSelection"]["userVerification"] == "required"
+
+    assert_equal session[:current_registration][:challenge], body["challenge"]
+  end
+
+  test "requires authentication to initiate Passkey creation" do
+    post create_options_passkeys_url
+
+    assert_response :redirect
+    assert_redirected_to new_session_url
+  end
+
+  test "creates passkey when user is authenticated" do
+    sign_in_as @user
+
+    post create_options_passkeys_url
+    challenge = session[:current_registration][:challenge]
+
+    public_key_credential = @client.create(
+      challenge: challenge,
+      user_verified: true,
+    )
+
+    assert_difference("WebauthnCredential.count", 1) do
+      post passkeys_url, params: {
+        credential: {
+          nickname: "My Passkey",
+          public_key_credential: public_key_credential.to_json
+        }
+      }
+    end
+
+    assert_redirected_to root_path
+    assert_match (/Security Key registered successfully/), flash[:notice]
+    assert_nil session[:current_registration]
+  end
+
+  test "does not create passkey when there is a Webauthn error" do
+    sign_in_as @user
+
+    post create_options_passkeys_url
+    challenge = session[:current_registration][:challenge]
+
+    public_key_credential = @client.create(
+      challenge: challenge,
+      user_verified: false,
+    )
+
+    assert_no_difference("WebauthnCredential.count") do
+      post passkeys_url, params: {
+        credential: {
+          nickname: "My Passkey",
+          public_key_credential: public_key_credential.to_json
+        }
+      }
+    end
+
+    assert_redirected_to new_passkey_path
+    assert_match (/Verification failed/), flash[:alert]
+    assert_nil session[:current_registration]
+  end
+
+  test "requires authentication to create passkey" do
+    post passkeys_url, params: {
+      credential: {
+        nickname: "My Passkey",
+        public_key_credential: "{}"
+      }
+    }
+
+    assert_response :redirect
+    assert_redirected_to new_session_url
+  end
+
+  test "deletes passkey when user is authenticated" do
+    2.times do |i|
+      WebauthnCredential.create!(
+        nickname: "My Passkey #{i}",
+        user: @user,
+        external_id: "external-id-#{i}",
+        public_key: "public-key-#{i}",
+        sign_count: 0,
+        authentication_factor: 0
+      )
+    end
+
+    sign_in_as @user
+
+    assert_difference("WebauthnCredential.count", -1) do
+      delete passkey_url(@user.webauthn_credentials.first)
+    end
+    assert_redirected_to root_path
+  end
+end

data/lib/generators/test_unit/webauthn_authentication/templates/test/controllers/webauthn_sessions_controller_test.rb

@@ -0,0 +1,125 @@
+require "test_helper"
+require "webauthn/fake_client"
+
+class WebauthnSessionsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+    @client = WebAuthn::FakeClient.new(WebAuthn.configuration.allowed_origins.first)
+
+    creation_options = WebAuthn::Credential.options_for_create(
+      user: { id: @user.webauthn_id, name: @user.email_address }
+    )
+    create_options = @client.create(challenge: creation_options.challenge)
+    credential = WebAuthn::Credential.from_create(create_options)
+
+    WebauthnCredential.create!(
+      nickname: "My Passkey",
+      user: @user,
+      external_id: credential.id,
+      public_key: credential.public_key,
+      sign_count: 0,
+      authentication_factor: 0
+    )
+  end
+
+  test "should return get_options" do
+    post get_options_webauthn_session_url
+
+    assert_response :success
+    body = JSON.parse(response.body)
+    assert body["challenge"].present?
+    assert body["userVerification"] == "required"
+
+    assert_equal session[:current_authentication][:challenge], body["challenge"]
+  end
+
+  test "should create session with valid credential" do
+    post get_options_webauthn_session_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = @client.get(challenge: challenge, user_verified: true)
+
+    post webauthn_session_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to root_path
+    assert_nil session[:current_authentication]
+  end
+
+  test "should not create session when there is a Webauthn error" do
+    post get_options_webauthn_session_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = @client.get(challenge: challenge, user_verified: false)
+
+    post webauthn_session_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to new_session_path
+    assert_match (/Verification failed/), flash[:alert]
+    assert_nil session[:current_authentication]
+  end
+
+  test "should not create session with unrecognized credential" do
+    post get_options_webauthn_session_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = @client.get(challenge: challenge, user_verified: true)
+    public_key_credential["id"] = "invalid-id"
+
+    post webauthn_session_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to new_session_path
+    assert_equal "Credential not recognized", flash[:alert]
+    assert_nil session[:current_authentication]
+  end
+
+  test "should not create session with a second factor credential" do
+    client = WebAuthn::FakeClient.new(WebAuthn.configuration.allowed_origins.first)
+
+    creation_options = WebAuthn::Credential.options_for_create(
+      user: { id: @user.webauthn_id, name: @user.email_address }
+    )
+    create_options = client.create(challenge: creation_options.challenge)
+    credential = WebAuthn::Credential.from_create(create_options)
+
+    WebauthnCredential.create!(
+      nickname: "Second Factor Key",
+      user: @user,
+      external_id: credential.id,
+      public_key: credential.public_key,
+      sign_count: 0,
+      authentication_factor: 1
+    )
+
+    post get_options_webauthn_session_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = client.get(challenge: challenge, user_verified: true)
+
+    post webauthn_session_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to new_session_path
+    assert_equal "Credential not recognized", flash[:alert]
+    assert_nil session[:current_authentication]
+  end
+
+  test "should destroy session" do
+    delete webauthn_session_url
+    assert_redirected_to new_session_path
+  end
+end

data/lib/generators/test_unit/webauthn_authentication/templates/test/system/manage_webauthn_credentials_test.rb

@@ -0,0 +1,76 @@
+require "application_system_test_case"
+require_relative "../test_helpers/virtual_authenticator_test_helper"
+
+class ManageWebauthnCredentialsTest < ApplicationSystemTestCase
+  include VirtualAuthenticatorTestHelper
+
+  def setup
+    user = User.create!(email_address: "alice@example.com", password: "S3cr3tP@ssw0rd!")
+    sign_in_as(user)
+    @authenticator = add_virtual_authenticator
+  end
+
+  def teardown
+    @authenticator.remove!
+  end
+
+  test "add credentials and sign in" do
+    visit root_path
+
+    click_on "Add Passkey"
+
+    fill_in("Security Key nickname", with: "Touch ID")
+    click_on "Add Security Key"
+
+    assert_current_path "/"
+    assert_selector "div", text: "Security Key registered successfully"
+    assert_selector "span", text: "Touch ID"
+
+    click_on "Sign out"
+    assert_selector("input[type=submit][value='Sign in']")
+
+    click_on "Sign In with Passkey"
+
+    assert_current_path "/"
+    assert_selector "h3", text: "Your Passkeys"
+  end
+
+  test "sign in with 2FA WebAuthn credential" do
+    visit root_path
+
+    click_on "Add Second Factor Key"
+
+    fill_in("Security Key nickname", with: "Touch ID")
+    click_on "Add Security Key"
+
+    assert_current_path "/"
+    assert_selector "div", text: "Security Key registered successfully"
+    assert_selector "span", text: "Touch ID"
+
+    click_on "Sign out"
+    assert_selector("input[type=submit][value='Sign in']")
+
+    fill_in "email_address", with: "alice@example.com"
+    fill_in "password", with: "S3cr3tP@ssw0rd!"
+    click_on "Sign in"
+
+    assert_selector "h3", text: "Two-factor authentication"
+    click_on "Use Security Key"
+
+    assert_current_path "/"
+    assert_selector "h3", text: "Your Passkeys"
+  end
+
+  private
+
+  def sign_in_as(user)
+    visit new_session_path
+
+    fill_in "email_address", with: user.email_address
+    fill_in "password", with: user.password
+
+    click_on "Sign in"
+
+    assert_selector "h3", text: "Your Passkeys"
+  end
+end

data/lib/generators/test_unit/webauthn_authentication/templates/test/test_helpers/virtual_authenticator_test_helper.rb

@@ -0,0 +1,9 @@
+module VirtualAuthenticatorTestHelper
+  def add_virtual_authenticator
+    options = ::Selenium::WebDriver::VirtualAuthenticatorOptions.new
+    options.user_verification = true
+    options.user_verified = true
+    options.resident_key = true
+    page.driver.browser.add_virtual_authenticator(options)
+  end
+end