devise-webauthn 0.0.0 → 0.1.1

data/README.md

@@ -1,8 +1,14 @@
 # Devise::Webauthn
+[![Gem Version](https://badge.fury.io/rb/devise-webauthn.svg)](https://badge.fury.io/rb/devise-webauthn)
 
-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/devise/webauthn`. To experiment with that code, run `bin/console` for an interactive prompt.
+Devise::Webauthn is a [Devise](https://github.com/heartcombo/devise) extension that adds [WebAuthn](https://www.w3.org/TR/2025/WD-webauthn-3-20250127/) support to your Rails application, allowing users to authenticate with [passkeys](https://www.w3.org/TR/2025/WD-webauthn-3-20250127/#passkey).
 
-TODO: Delete this and the text above, and describe your gem
+## Requirements
+
+- **Ruby**: 2.7+
+- **Stimulus Rails**: This gem requires [stimulus-rails](https://github.com/hotwired/stimulus-rails) to be installed and configured in your application.
+> **Note:** Stimulus Rails is needed for the generated code to work out of the box.  
+> If you prefer not to have this dependency, you’ll need to manually implement the JavaScript logic for WebAuthn interactions.
 
 ## Installation
 
@@ -14,7 +20,7 @@ gem 'devise-webauthn'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 
@@ -22,17 +28,125 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+First, ensure you have Devise set up in your Rails application. For a full guide on setting up Devise, refer to the [Devise documentation](https://github.com/heartcombo/devise?tab=readme-ov-file#getting-started).
+Then, follow these steps to integrate Devise::Webauthn:
+1. **Run Devise::Webauthn Generator:**
+   Run the generator to set up necessary configurations, migrations, and Stimulus controller:
+   ```bash
+   $ bin/rails generate devise:webauthn:install
+   ```
+
+   You can optionally specify a different resource name (defaults to "user"):
+   ```bash
+   $ bin/rails generate devise:webauthn:install --resource-name=RESOURCE_NAME
+   ```
+
+   The generator will:
+    - Create the WebAuthn initializer (`config/initializers/webauthn.rb`)
+    - Generate the `WebauthnCredential` model and migration
+    - Add `webauthn_id` field to your devise model (e.g., `User`)
+    - Install the Stimulus controller
+
+2. **Run Migrations:**
+   After running the generator, execute the migrations to update your database schema:
+   ```bash
+   $ bin/rails db:migrate
+   ```
+
+3. **Update Your Devise Model:**
+   Add `:passkey_authenticatable` to your Devise model (e.g., `User`):
+   ```ruby
+   class User < ApplicationRecord
+     devise :database_authenticatable, :registerable,
+            :recoverable, :rememberable, :validatable, :passkey_authenticatable
+   end
+   ```
+
+4. **Configure WebAuthn Settings:**
+   Update the generated initializer file `config/initializers/webauthn.rb` with your application's specific settings, such as `rp_name`, and `allowed_origins`. For example:
+   ```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
+    ```
+
+## How It Works
+
+### Adding Passkeys
+Signed-in users can add passkeys by visiting `/users/passkeys/new`.
+
+### Sign In with Passkeys
+When a user visits `/users/sign_in` they can choose to authenticate using a passkey. The authentication flow is handled by `PasskeysAuthenticatable` strategy.
+
+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.
+
+## Customization
+
+### Customizing Views
+Similar to [views customization on Devise](https://github.com/heartcombo/devise?tab=readme-ov-file#configuring-views), to customize the views, you can copy the view files from the gem into your application. Run the following command:
+```bash
+$ bin/rails generate devise:webauthn:views
+```
+
+If you want to customize only specific views, you can copy them individually. For example, to copy only the passkeys views:
+```bash
+$ bin/rails generate devise:webauthn:views -v passkeys
+```
+
+### Helper methods
+Devise::Webauthn provides helpers that can be used in your views. For example, for a resource named `user`, you can use the following helpers:
+
+To add a button for logging in with passkeys:
+```erb
+<%= login_with_passkey_button("Log in with passkeys", session_path: user_session_path) %>
+```
+
+To add a passkeys creation form:
+```erb
+<%= passkey_creation_form_for(current_user) do |form| %>
+  <%= form.label :name, 'Passkey name' %>
+  <%= form.text_field :name, required: true %>
+  <%= form.submit 'Create Passkey' %>
+<% end %>
+```
+
+### Customizing Controllers
+Similar to [controllers customization on Devise](https://github.com/heartcombo/devise?tab=readme-ov-file#configuring-controllers), you can customize the Devise::Webauthn controllers.
+
+1. Create your custom controllers using the generator which requires a scope:
+```bash
+$ bin/rails generate devise:webauthn:controllers [scope]
+```
+
+2. Tell the router to use your custom controllers. For example, if your scope is `users`:
+```ruby
+devise_for :users, controllers: {
+  passkeys: 'users/passkeys'
+}
+```
+
+3. Change or extend the generated controllers as needed.
+
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+To run the linter, use `bundle exec rubocop`.
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Before submitting a pull request, ensure that tests and linter pass.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/devise-webauthn.
+Bug reports and pull requests are welcome on GitHub at https://github.com/cedarcode/devise-webauthn.
 
 ## License
 

data/Rakefile

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/app/controllers/devise/passkeys_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Devise
+  class PasskeysController < DeviseController
+    before_action :authenticate_scope!
+
+    def new; end
+
+    def create
+      passkey_from_params = WebAuthn::Credential.from_create(JSON.parse(params[:public_key_credential]))
+
+      if verify_and_save_passkey(passkey_from_params)
+        set_flash_message! :notice, :passkey_created
+      else
+        set_flash_message! :alert, :passkey_verification_failed, scope: :"devise.failure"
+      end
+      redirect_to after_update_path
+    rescue WebAuthn::Error
+      set_flash_message! :alert, :passkey_verification_failed, scope: :"devise.failure"
+      redirect_to after_update_path
+    ensure
+      session.delete(:webauthn_challenge)
+    end
+
+    def destroy
+      resource.passkeys.destroy(params[:id])
+      redirect_to after_update_path
+    end
+
+    private
+
+    def authenticate_scope!
+      send(:"authenticate_#{resource_name}!", force: true)
+      self.resource = send(:"current_#{resource_name}")
+    end
+
+    def verify_and_save_passkey(passkey_from_params)
+      passkey_from_params.verify(
+        session[:webauthn_challenge],
+        user_verification: true
+      )
+
+      resource.passkeys.create(
+        external_id: passkey_from_params.id,
+        name: params[:name],
+        public_key: passkey_from_params.public_key,
+        sign_count: passkey_from_params.sign_count
+      )
+    end
+
+    # The default url to be used after creating a passkey. You can overwrite
+    # this method in your own PasskeysController.
+    def after_update_path
+      new_passkey_path(resource_name)
+    end
+  end
+end

data/app/views/devise/passkeys/new.html.erb

@@ -0,0 +1,5 @@
+<%= passkey_creation_form_for(resource) do |form| %>
+  <%= form.label :name, 'Passkey name' %>
+  <%= form.text_field :name, required: true %>
+  <%= form.submit 'Create Passkey' %>
+<% end %>

data/app/views/devise/sessions/new.html.erb

@@ -0,0 +1,28 @@
+<h2>Log in</h2>
+
+<%= form_for(resource, as: resource_name, url: session_path(resource_name)) do |f| %>
+  <div class="field">
+    <%= f.label :email %><br />
+    <%= f.email_field :email, autofocus: true, autocomplete: "email" %>
+  </div>
+
+  <div class="field">
+    <%= f.label :password %><br />
+    <%= f.password_field :password, autocomplete: "current-password" %>
+  </div>
+
+  <% if devise_mapping.rememberable? %>
+    <div class="field">
+      <%= f.check_box :remember_me %>
+      <%= f.label :remember_me %>
+    </div>
+  <% end %>
+
+  <div class="actions">
+    <%= f.submit "Log in" %>
+  </div>
+<% end %>
+
+<%= login_with_passkey_button("Log in with passkeys", session_path: session_path(resource_name)) %>
+
+<%= render "devise/shared/links" %>

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "bundler/setup"
 require "devise/webauthn"

data/bin/rails

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This command will automatically be run when you run "rails" with Rails gems
+# installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path("..", __dir__)
+ENGINE_PATH = File.expand_path("../lib/devise/webauthn/engine", __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup" if File.exist?(ENV["BUNDLE_GEMFILE"])
+
+require "rails/all"
+require "rails/engine/commands"

data/config/locales/en.yml

@@ -0,0 +1,8 @@
+en:
+  devise:
+    passkeys:
+      passkey_created: "Passkey created successfully."
+      passkey_creation_failed: "Passkey creation failed."
+    failure:
+      passkey_not_found: "Your passkey doesn't exist or is not valid."
+      passkey_verification_failed: "Passkey verification failed."

data/config.ru

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler"
+require "combustion"
+
+Combustion.initialize! :active_model, :active_record, :action_controller, :action_view do
+  config.load_defaults Rails.version.to_f
+end
+run Combustion::Application

data/devise-webauthn.gemspec

@@ -1,29 +1,34 @@
+# frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "devise/webauthn/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "devise-webauthn"
   spec.version       = Devise::Webauthn::VERSION
-  spec.authors       = ["Braulio Martinez"]
-  spec.email         = ["braulio@cedarcode.com"]
+  spec.authors       = ["Cedarcode"]
+  spec.email         = ["webauthn@cedarcode.com"]
 
-  spec.summary       = %q{Devise extension to support WebAuthn.}
+  spec.summary       = "Devise extension to support WebAuthn."
   spec.license       = "MIT"
 
+  spec.homepage      = "https://github.com/cedarcode/devise-webauthn"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.required_ruby_version = ">= 2.7"
 
-  spec.required_ruby_version = ">= 2.3"
-
-  spec.add_development_dependency "bundler", "~> 1.17"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_dependency "devise", "~> 4.9"
+  spec.add_dependency "webauthn", "~> 3.0"
 end

data/gemfiles/rails_7_1.gemfile

@@ -0,0 +1,23 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.5"
+gem "capybara", "~> 3.39"
+gem "combustion", "~> 1.3"
+gem "importmap-rails", "~> 2.0"
+gem "propshaft", "~> 1.2"
+gem "pry-byebug", "~> 3.10"
+gem "puma", "~> 6.6"
+gem "rails", "~> 7.1"
+gem "rspec-rails", "~> 7.1"
+gem "rubocop", "~> 1.79"
+gem "rubocop-rails", "~> 2.32"
+gem "rubocop-rspec", "~> 3.6"
+gem "selenium-webdriver"
+gem "sqlite3", "~> 1.7"
+gem "stimulus-rails", "~> 1.3"
+gem "psych", "~> 4.0"
+gem "rack", "~> 2.2"
+
+gemspec path: "../"

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.5"
+gem "capybara", "~> 3.40"
+gem "combustion", "~> 1.3"
+gem "importmap-rails", "~> 2.2"
+gem "propshaft", "~> 1.2"
+gem "pry-byebug", "~> 3.11"
+gem "puma", "~> 6.6"
+gem "rails", "~> 7.2"
+gem "rspec-rails", "~> 8.0"
+gem "rubocop", "~> 1.79"
+gem "rubocop-rails", "~> 2.32"
+gem "rubocop-rspec", "~> 3.6"
+gem "selenium-webdriver"
+gem "sqlite3", "~> 2.7"
+gem "stimulus-rails", "~> 1.3"
+
+gemspec path: "../"

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.5"
+gem "capybara", "~> 3.40"
+gem "combustion", "~> 1.3"
+gem "importmap-rails", "~> 2.2"
+gem "propshaft", "~> 1.2"
+gem "pry-byebug", "~> 3.11"
+gem "puma", "~> 6.6"
+gem "rails", "~> 8.0"
+gem "rspec-rails", "~> 8.0"
+gem "rubocop", "~> 1.79"
+gem "rubocop-rails", "~> 2.32"
+gem "rubocop-rspec", "~> 3.6"
+gem "selenium-webdriver"
+gem "sqlite3", "~> 2.7"
+gem "stimulus-rails", "~> 1.3"
+
+gemspec path: "../"

data/gemfiles/rails_edge.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.5"
+gem "capybara", "~> 3.40"
+gem "combustion", "~> 1.3"
+gem "importmap-rails", "~> 2.2"
+gem "propshaft", "~> 1.2"
+gem "pry-byebug", "~> 3.11"
+gem "puma", "~> 6.6"
+gem "rails", branch: "main", git: "https://github.com/rails/rails"
+gem "rspec-rails", "~> 8.0"
+gem "rubocop", "~> 1.79"
+gem "rubocop-rails", "~> 2.32"
+gem "rubocop-rspec", "~> 3.6"
+gem "selenium-webdriver"
+gem "sqlite3", "~> 2.7"
+gem "stimulus-rails", "~> 1.3"
+
+gemspec path: "../"

data/lib/devise/models/passkey_authenticatable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "devise/strategies/passkey_authenticatable"
+
+module Devise
+  module Models
+    module PasskeyAuthenticatable
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :passkeys, dependent: :destroy, class_name: "WebauthnCredential"
+
+        validates :webauthn_id, uniqueness: true, allow_blank: true
+
+        after_initialize do
+          self.webauthn_id ||= WebAuthn.generate_user_id
+        end
+      end
+    end
+  end
+end

data/lib/devise/strategies/passkey_authenticatable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Devise
+  module Strategies
+    class PasskeyAuthenticatable < Warden::Strategies::Base
+      def valid?
+        passkey_param.present? && session[:authentication_challenge].present?
+      end
+
+      def authenticate!
+        passkey_from_params = WebAuthn::Credential.from_get(JSON.parse(passkey_param))
+        stored_passkey = WebauthnCredential.find_by(external_id: passkey_from_params.id)
+
+        return fail!(:passkey_not_found) if stored_passkey.blank?
+
+        verify_passkeys(passkey_from_params, stored_passkey)
+
+        success!(stored_passkey.user)
+      rescue WebAuthn::Error
+        fail!(:passkey_verification_failed)
+      ensure
+        session.delete(:authentication_challenge)
+      end
+
+      private
+
+      def passkey_param
+        params[:public_key_credential]
+      end
+
+      def verify_passkeys(passkey_from_params, stored_passkey)
+        passkey_from_params.verify(
+          session[:authentication_challenge],
+          public_key: stored_passkey.public_key,
+          sign_count: stored_passkey.sign_count,
+          user_verification: true
+        )
+
+        stored_passkey.update!(sign_count: passkey_from_params.sign_count)
+      end
+    end
+  end
+end
+
+Warden::Strategies.add(:passkey_authenticatable, Devise::Strategies::PasskeyAuthenticatable)

data/lib/devise/webauthn/engine.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Devise
+  module Webauthn
+    class Engine < ::Rails::Engine
+      isolate_namespace Devise::Webauthn
+
+      initializer "devise.webauthn.add_module" do
+        Devise.add_module(
+          :passkey_authenticatable,
+          {
+            model: "devise/models/passkey_authenticatable",
+            strategy: true,
+            route: { passkey_authentication: [] }
+          }
+        )
+      end
+
+      initializer "devise.webauthn.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Devise::Webauthn::CredentialsHelper
+        end
+      end
+
+      initializer "devise.webauthn.url_helpers" do
+        Devise.include_helpers(Devise::Webauthn)
+      end
+    end
+  end
+end

data/lib/devise/webauthn/helpers/credentials_helper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Devise
+  module Webauthn
+    module CredentialsHelper
+      def passkey_creation_form_for(resource, form_classes: nil, &block)
+        form_with(
+          url: passkeys_path(resource),
+          method: :post,
+          class: form_classes,
+          data: {
+            action: "webauthn-credentials#create:prevent",
+            controller: "webauthn-credentials",
+            webauthn_credentials_options_param: create_passkey_options(resource)
+          }
+        ) do |f|
+          concat f.hidden_field(:public_key_credential,
+                                data: { "webauthn-credentials-target": "credentialHiddenInput" })
+          concat capture(f, &block)
+        end
+      end
+
+      def login_with_passkey_button(text = nil, session_path:, button_classes: nil, form_classes: nil, &block)
+        form_with(
+          url: session_path,
+          method: :post,
+          data: {
+            action: "webauthn-credentials#get:prevent",
+            controller: "webauthn-credentials",
+            webauthn_credentials_options_param: webauthn_authentication_options
+          },
+          class: form_classes
+        ) do |f|
+          concat f.hidden_field(:public_key_credential,
+                                data: { "webauthn-credentials-target": "credentialHiddenInput" })
+          concat f.button(text, type: "submit", class: button_classes, &block)
+        end
+      end
+
+      private
+
+      def create_passkey_options(resource)
+        @create_passkey_options ||= begin
+          options = WebAuthn::Credential.options_for_create(
+            user: {
+              id: resource.webauthn_id,
+              name: resource.email
+            },
+            exclude: resource.passkeys.pluck(:external_id),
+            authenticator_selection: {
+              resident_key: "required",
+              user_verification: "required"
+            }
+          )
+
+          # Store challenge in session for later verification
+          session[:webauthn_challenge] = options.challenge
+
+          options
+        end
+      end
+
+      def webauthn_authentication_options
+        @webauthn_authentication_options ||= begin
+          options = WebAuthn::Credential.options_for_get(
+            user_verification: "required"
+          )
+
+          # Store challenge in session for later verification
+          session[:authentication_challenge] = options.challenge
+
+          options
+        end
+      end
+    end
+  end
+end

data/lib/devise/webauthn/routes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActionDispatch
+  module Routing
+    class Mapper
+      protected
+
+      def devise_passkey_authentication(_mapping, controllers)
+        resources :passkeys, only: %i[new create destroy], controller: controllers[:passkeys]
+      end
+    end
+  end
+end

data/lib/devise/webauthn/test/authenticator_helpers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Devise
+  module Webauthn
+    module Test
+      module AuthenticatorHelpers
+        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
+    end
+  end
+end