webauthn-rails 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c23bb425dcafa1c050ddda0f7533a264ea071451215000d54da251c712a5189c
-  data.tar.gz: fa31284ff35f0804a31ef43eeb5e0905407581b197e4ba331ad52a26f33a775e
+  metadata.gz: 20ded36acb2b7a3f4d67cdd4e860dc41e6f8490bb9143be6a0575117e1e7a84e
+  data.tar.gz: 8b2d46393c0d24e340b82f7f5d908e34fdd7cedb30501b8e8ba9663f217c23b9
 SHA512:
-  metadata.gz: 7e67df5d493f1d58d9567198be453b130a4ce7f6a0bdfb8ef98227bfec80255d79fbb42d8eb11656f30f1a7a0dc2f6693f027fa4160e9ceec02aabafd87a833a
-  data.tar.gz: 4b57092b8e648edd83f61b74801d4c134e74c94c7caf63dd1bf0988c50bdc564a450f44e0ddb4a8fdb578162683997c4c2e42f54500faedfdf2c068d3854b544
+  metadata.gz: 89c27f2bd69320aef0d3a36207788478ce85e7eea4b1f722950ec12749fa3fdcaa5a3eed1f322b77425d5d8b8e1d848cf912d84cd55c7872fa2142750626b345
+  data.tar.gz: d125c6229d26da7d19794479091ec59b706e10166a70a5e3f228a4d3571906a5b3d3a3db23c81cfb2c735e56c91c9bdf1ee01f249689761641d46aad1319f8ff

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,103 @@
+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 "create_options" 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 "create_options unauthenticated" do
+    post create_options_passkeys_url
+
+    assert_response :redirect
+    assert_redirected_to new_session_url
+  end
+
+  test "create" 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 "create with 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 "create unauthenticated" do
+    post passkeys_url
+
+    assert_response :redirect
+    assert_redirected_to new_session_url
+  end
+
+  test "destroy" do
+    credential = WebauthnCredential.passkey.create!(
+      nickname: "My Passkey",
+      user: @user,
+      external_id: "external-id",
+      public_key: "public-key",
+      sign_count: 0,
+    )
+
+    sign_in_as @user
+
+    assert_difference("WebauthnCredential.count", -1) do
+      delete passkey_url(credential)
+    end
+    assert_redirected_to root_path
+  end
+end

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

@@ -0,0 +1,131 @@
+require "test_helper"
+require "webauthn/fake_client"
+
+class SecondFactorAuthenticationsControllerTest < 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 },
+      authenticator_selection: { resident_key: "discouraged", user_verification: "discouraged" }
+    )
+    create_options = @client.create(challenge: creation_options.challenge)
+    credential = WebAuthn::Credential.from_create(create_options)
+
+    WebauthnCredential.second_factor.create!(
+      nickname: "My Security Key",
+      user: @user,
+      external_id: credential.id,
+      public_key: credential.public_key,
+      sign_count: 0
+    )
+  end
+
+  test "get_options" do
+    post session_path, params: { email_address: @user.email_address, password: "password" }
+
+    post get_options_second_factor_authentication_url
+
+    assert_response :success
+    body = JSON.parse(response.body)
+    assert body["challenge"].present?
+    assert body["userVerification"] == "discouraged"
+
+    assert_equal session[:current_authentication][:challenge], body["challenge"]
+  end
+
+  test "create" do
+    post session_path, params: { email_address: @user.email_address, password: "password" }
+
+    post get_options_second_factor_authentication_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = @client.get(challenge: challenge, user_verified: false)
+
+    post second_factor_authentication_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to root_path
+    assert_nil session[:current_authentication]
+  end
+
+  test "create with a passkey" 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 },
+      authenticator_selection: { resident_key: "discouraged", user_verification: "discouraged" }
+    )
+    create_options = client.create(challenge: creation_options.challenge)
+    credential = WebAuthn::Credential.from_create(create_options)
+
+
+    WebauthnCredential.passkey.create!(
+      nickname: "My Security Key",
+      user: @user,
+      external_id: credential.id,
+      public_key: credential.public_key,
+      sign_count: 0
+    )
+
+    post session_path, params: { email_address: @user.email_address, password: "password" }
+
+    post get_options_second_factor_authentication_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = client.get(challenge: challenge, user_verified: false)
+
+    post second_factor_authentication_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to root_path
+    assert_nil session[:current_authentication]
+  end
+
+  test "create with WebAuthn error" do
+    post session_path, params: { email_address: @user.email_address, password: "password" }
+
+    post get_options_second_factor_authentication_url
+
+    public_key_credential = @client.get(
+      user_verified: false
+    )
+
+    post second_factor_authentication_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to new_second_factor_authentication_path
+    assert_match (/Verification failed/), flash[:alert]
+    assert_nil session[:current_authentication]
+  end
+
+  test "create with unrecognized credential" do
+    post session_path, params: { email_address: @user.email_address, password: "password" }
+
+    post get_options_second_factor_authentication_url
+    challenge = session[:current_authentication][:challenge]
+
+    public_key_credential = @client.get(challenge: challenge, user_verified: false)
+    public_key_credential["id"]= "invalid-id"
+
+    post second_factor_authentication_url, params: {
+      session: {
+        public_key_credential: public_key_credential.to_json
+      }
+    }
+
+    assert_redirected_to new_second_factor_authentication_path
+    assert_match (/Credential not recognized/), flash[:alert]
+    assert_nil session[:current_authentication]
+  end
+end