devise-webauthn 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b2e30cdcc561dc53baf71ada282183019321b12b1820afc6107b67c000c1297
-  data.tar.gz: f01204525d77a874a131b4a4f13928faa9d6819160792bc12efdb0ad9b9b6d5b
+  metadata.gz: 8083a823cce7edf858475a062ea009193c3a86cf9b4a821db1dd2715430580d4
+  data.tar.gz: df00de569113a642c13f87cc4f6c93836acb5c5df1ef1cecfe492b01247a17aa
 SHA512:
-  metadata.gz: 3c4c14744bbaeb2ed55957baa3d868dd5eb4ebb48300a13a17cd110c329a373f18f97706da1d08f2cfe48d09d5e7a96d0d409c8af485658a55c357f121dbadde
-  data.tar.gz: 3456027c51e2aab1434a47afe3943e4e75910d38bba9e0dc551662cc0a0f4708d52d108e30229fe390f93f89e8d411d7be669cc9c2ffdb31dea2aa41aa280669
+  metadata.gz: ce764390d121fc68bd1732d655700ccae382ced384a24f350256f2bb633910d0038972637a8e9f4f5e512d0e13030c53851f7288733fb233e8d86fe00ab5c8b8
+  data.tar.gz: d2072d245253437be40005c81b9879f22f0a7c0fa3e0e3cd39b9b03f812aa05cdcd7404cbd4123afac473785364472f3e025dbdf025ae3f74af117854dcbca38

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [cedarcode]

data/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  release:
+    name: Publish to Rubygems
+
+    runs-on: ubuntu-latest
+
+    environment: release
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1

data/.github/workflows/ruby.yml

@@ -32,6 +32,7 @@ jobs:
           - 2.7
         gemfile:
           - rails_edge
+          - rails_8_1
           - rails_8_0
           - rails_7_2
           - rails_7_1
@@ -39,11 +40,15 @@ jobs:
         exclude:
           - ruby: 3.1
             gemfile: rails_edge
+          - ruby: 3.1
+            gemfile: rails_8_1
           - ruby: 3.1
             gemfile: rails_8_0
 
           - ruby: 3.0
             gemfile: rails_edge
+          - ruby: 3.0
+            gemfile: rails_8_1
           - ruby: 3.0
             gemfile: rails_8_0
           - ruby: 3.0
@@ -51,6 +56,8 @@ jobs:
 
           - ruby: 2.7
             gemfile: rails_edge
+          - ruby: 2.7
+            gemfile: rails_8_1
           - ruby: 2.7
             gemfile: rails_8_0
           - ruby: 2.7

data/Appraisals

@@ -4,6 +4,10 @@ appraise "rails-edge" do
   gem "rails", github: "rails/rails", branch: "main"
 end
 
+appraise "rails-8_1" do
+  gem "rails", "~> 8.1"
+end
+
 appraise "rails-8_0" do
   gem "rails", "~> 8.0"
 end

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## [v0.2.1](https://github.com/cedarcode/devise-webauthn/compare/v0.2.0...v0.2.1/) - 2025-12-10
+
+- Add form helpers for security key registration and 2FA authentication.
+- Fix incorrect call to `resource_name` instead of using passed `resource` param in `login_with_security_key_button` helper.
+- Fix `NoMethodError` when calling `second_factor_enabled?` on resources without 2FA.
+- Avoid assuming `email` as the authentication key of the resource in form helpers.
+
 ## [v0.2.0](https://github.com/cedarcode/devise-webauthn/compare/v0.1.2...v0.2.0/) - 2025-12-03
 
 - Add new `webauthn_two_factor_authenticatable` module for enabling 2FA using WebAuthn credentials.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    devise-webauthn (0.2.0)
+    devise-webauthn (0.2.1)
       devise (~> 4.9)
       webauthn (~> 3.0)
 

data/README.md

@@ -1,7 +1,7 @@
 # Devise::Webauthn
 [![Gem Version](https://badge.fury.io/rb/devise-webauthn.svg)](https://badge.fury.io/rb/devise-webauthn)
 
-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).
+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) and use [security keys](https://www.w3.org/TR/webauthn-3/#server-side-credential) for two factor authentication.
 
 ## Requirements
 
@@ -54,11 +54,12 @@ Then, follow these steps to integrate Devise::Webauthn:
    ```
 
 3. **Update Your Devise Model:**
-   Add `:passkey_authenticatable` to your Devise model (e.g., `User`):
+   Add `:passkey_authenticatable` to your Devise model (e.g., `User`) for passkeys authentication and `:webauthn_two_factor_authenticatable` for WebAuthn-based 2FA if desired. For example:
    ```ruby
    class User < ApplicationRecord
      devise :database_authenticatable, :registerable,
-            :recoverable, :rememberable, :validatable, :passkey_authenticatable
+            :recoverable, :rememberable, :validatable,
+            :passkey_authenticatable, :webauthn_two_factor_authenticatable
    end
    ```
 
@@ -77,10 +78,12 @@ Then, follow these steps to integrate Devise::Webauthn:
 
 ## How It Works
 
-### Adding Passkeys
+### Passkey authentication
+
+#### Adding Passkeys
 Signed-in users can add passkeys by visiting `/users/passkeys/new`.
 
-### Sign In with Passkeys
+#### 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:
@@ -89,6 +92,22 @@ The WebAuthn passkey sign-in flow works as follows:
 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.
 
+### Two-Factor Authentication (2FA) with WebAuthn
+
+#### Adding Security Keys for 2FA
+Signed-in users can add security keys by visiting `/users/second_factor_webauthn_credentials/new`.
+
+#### 2FA Sign In with Security Keys
+When a user that has 2FA enabled (i.e., has registered passkeys or security keys) visits `/users/sign_in`, after entering their primary credentials (e.g., email and password), they will be prompted to complete the second factor authentication using WebAuthn. The authentication flow is handled by `WebauthnTwoFactorAuthenticatable` strategy.
+
+The two factor authentication flow with WebAuthn works as follows:
+1. User enters their primary credentials (e.g., email and password) and submits the form.
+2. If the user has 2FA enabled, they are redirected to a second factor authentication page.
+3. User clicks "Use security key", starting a WebAuthn authentication ceremony.
+4. Browser shows available credentials (which can be both passkeys and security keys).
+5. User selects a credential and verifies with their [authenticator](https://www.w3.org/TR/webauthn-3/#webauthn-authenticator).
+6. The server verifies the response and signs in the user.
+
 ## Customization
 
 ### Customizing Views

data/app/controllers/devise/second_factor_webauthn_credentials_controller.rb

@@ -4,22 +4,7 @@ module Devise
   class SecondFactorWebauthnCredentialsController < DeviseController
     before_action :authenticate_scope!
 
-    def new
-      @options = WebAuthn::Credential.options_for_create(
-        user: {
-          id: resource.webauthn_id,
-          name: resource.email
-        },
-        exclude: resource.webauthn_credentials.pluck(:external_id),
-        authenticator_selection: {
-          resident_key: "discouraged",
-          user_verification: "discouraged"
-        }
-      )
-
-      # Store challenge in session for later verification
-      session[:webauthn_challenge] = @options.challenge
-    end
+    def new; end
 
     def create
       security_key_from_params = WebAuthn::Credential.from_create(JSON.parse(params[:public_key_credential]))

data/app/controllers/devise/two_factor_authentications_controller.rb

@@ -6,13 +6,7 @@ module Devise
     prepend_before_action :ensure_sign_in_initiated
     prepend_before_action :require_no_authentication
 
-    def new
-      @options = WebAuthn::Credential.options_for_get(
-        allow: @resource.webauthn_credentials.pluck(:external_id),
-        user_verification: "discouraged"
-      )
-      session[:two_factor_authentication_challenge] = @options.challenge
-    end
+    def new; end
 
     def create
       self.resource = warden.authenticate!(auth_options)

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

@@ -1,14 +1,4 @@
-<%= form_with(
-  url: second_factor_webauthn_credentials_path(resource),
-  method: :post,
-  data: {
-    action: "webauthn-credentials#create:prevent",
-    controller: "webauthn-credentials",
-    webauthn_credentials_options_param: @options,
-  }
-) do |form| %>
-  <%= form.hidden_field(:public_key_credential,
-                        data: { "webauthn-credentials-target": "credentialHiddenInput" }) %>
+<%= security_key_creation_form_for(resource) do |form| %>
   <%= form.label :name, 'Security Key name' %>
   <%= form.text_field :name, required: true %>
   <%= form.submit 'Create Security Key' %>

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

@@ -1,12 +1 @@
-<%= form_with(
-  url: two_factor_authentication_path(resource_name),
-  method: :post,
-  data: {
-    action: "webauthn-credentials#get:prevent",
-    controller: "webauthn-credentials",
-    webauthn_credentials_options_param: @options
-  },
-) do |f| %>
-  <%= f.hidden_field(:public_key_credential, data: { "webauthn-credentials-target": "credentialHiddenInput" }) %>
-  <%= f.button('Use security key', type: "submit") %>
-<% end %>
+<%= login_with_security_key_button('Use security key', resource: @resource) %>

data/config/locales/en.yml

@@ -2,7 +2,6 @@ en:
   devise:
     passkeys:
       passkey_created: "Passkey created successfully."
-      passkey_creation_failed: "Passkey creation failed."
     second_factor_webauthn_credentials:
       security_key_created: "Security Key created successfully."
     failure:

data/gemfiles/rails_8_1.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.1"
+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/strategies/database_authenticatable.rb

@@ -11,7 +11,7 @@ module Devise
         hashed = false
 
         if validate(resource){ hashed = true; resource.valid_password?(password) }
-          if resource.second_factor_enabled?
+          if second_factor_enabled?(resource)
             session[:current_authentication_resource_id] = resource.id
             request.flash[:notice] = two_factor_required_message
             request.commit_flash
@@ -41,6 +41,10 @@ module Devise
       def two_factor_required_message
         I18n.t(:"#{scope}.two_factor_required", resource_name: scope, scope: "devise.failure", default: :two_factor_required)
       end
+
+      def second_factor_enabled?(resource)
+        resource.respond_to?(:second_factor_enabled?) && resource.second_factor_enabled?
+      end
     end
   end
 end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/ModuleLength
 module Devise
   module Webauthn
     module CredentialsHelper
@@ -27,7 +28,41 @@ module Devise
           data: {
             action: "webauthn-credentials#get:prevent",
             controller: "webauthn-credentials",
-            webauthn_credentials_options_param: webauthn_authentication_options
+            webauthn_credentials_options_param: passkey_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
+
+      def security_key_creation_form_for(resource, form_classes: nil, &block)
+        form_with(
+          url: second_factor_webauthn_credentials_path(resource),
+          method: :post,
+          class: form_classes,
+          data: {
+            action: "webauthn-credentials#create:prevent",
+            controller: "webauthn-credentials",
+            webauthn_credentials_options_param: create_security_key_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_security_key_button(text = nil, resource:, button_classes: nil, form_classes: nil, &block)
+        form_with(
+          url: two_factor_authentication_path(resource),
+          method: :post,
+          data: {
+            action: "webauthn-credentials#get:prevent",
+            controller: "webauthn-credentials",
+            webauthn_credentials_options_param: security_key_authentication_options(resource)
           },
           class: form_classes
         ) do |f|
@@ -44,7 +79,7 @@ module Devise
           options = WebAuthn::Credential.options_for_create(
             user: {
               id: resource.webauthn_id,
-              name: resource.email
+              name: resource_human_palatable_identifier
             },
             exclude: resource.passkeys.pluck(:external_id),
             authenticator_selection: {
@@ -60,8 +95,8 @@ module Devise
         end
       end
 
-      def webauthn_authentication_options
-        @webauthn_authentication_options ||= begin
+      def passkey_authentication_options
+        @passkey_authentication_options ||= begin
           options = WebAuthn::Credential.options_for_get(
             user_verification: "required"
           )
@@ -72,6 +107,49 @@ module Devise
           options
         end
       end
+
+      def create_security_key_options(resource)
+        @create_security_key_options ||= begin
+          options = WebAuthn::Credential.options_for_create(
+            user: {
+              id: resource.webauthn_id,
+              name: resource_human_palatable_identifier
+            },
+            exclude: resource.webauthn_credentials.pluck(:external_id),
+            authenticator_selection: {
+              resident_key: "discouraged",
+              user_verification: "discouraged"
+            }
+          )
+
+          # Store challenge in session for later verification
+          session[:webauthn_challenge] = options.challenge
+
+          options
+        end
+      end
+
+      def security_key_authentication_options(resource)
+        @security_key_authentication_options ||= begin
+          options = WebAuthn::Credential.options_for_get(
+            allow: resource.webauthn_credentials.pluck(:external_id),
+            user_verification: "discouraged"
+          )
+
+          # Store challenge in session for later verification
+          session[:two_factor_authentication_challenge] = options.challenge
+
+          options
+        end
+      end
+
+      def resource_human_palatable_identifier
+        authentication_keys = resource.class.authentication_keys
+        authentication_keys = authentication_keys.keys if authentication_keys.is_a?(Hash)
+
+        authentication_keys.filter_map { |authentication_key| resource.public_send(authentication_key) }.first
+      end
     end
   end
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/devise/webauthn/version.rb

@@ -2,6 +2,6 @@
 
 module Devise
   module Webauthn
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: devise-webauthn
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Cedarcode
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: devise
@@ -38,13 +37,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description:
 email:
 - webauthn@cedarcode.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/FUNDING.yml"
+- ".github/workflows/release.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
@@ -73,6 +73,7 @@ files:
 - gemfiles/rails_7_1.gemfile
 - gemfiles/rails_7_2.gemfile
 - gemfiles/rails_8_0.gemfile
+- gemfiles/rails_8_1.gemfile
 - gemfiles/rails_edge.gemfile
 - lib/devise/models/passkey_authenticatable.rb
 - lib/devise/models/webauthn_credential_authenticatable.rb
@@ -105,7 +106,6 @@ metadata:
   source_code_uri: https://github.com/cedarcode/devise-webauthn
   changelog_uri: https://github.com/cedarcode/devise-webauthn/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -120,8 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.1
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Devise extension to support WebAuthn.
 test_files: []