passkeys-rails 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1967aeb595e4864973402bf8108fe5a56b668678b8ed56aafbc403b164c628d
-  data.tar.gz: c96c2cd39bedbc138c1cd35248432d9cf7626c5a96007b91981741eb6f56e478
+  metadata.gz: 631e7354b6296e5fcc14144ba3bd305ca9047c31f9e5b0173f5eb7123f14fa71
+  data.tar.gz: 65e1f2d4cbd179ddee7449318b49a838d166db64db9221e1f079ac7e57735bf3
 SHA512:
-  metadata.gz: 3eb9182122196e3c94b5ebb78b0984785c39fb194b6d7f5f95432eb63e53482be0190fe24bc2af914a38377ee1a82df80932b11c16f918d155fdbaa731b5a052
-  data.tar.gz: e16475967c805796248fb3188667456e31fd833f841b98d16c28a6b5964e59170d349a018580a5e1ab312f18f7a9f7f16693b612d70d97f6ce91a5a77a9e5db4
+  metadata.gz: f8799f782713ae01ca312506c39ef2bed3a56448fb0b4e78d4c75a441b4a3fbac731a5bcf3f23421f9b240e84346f80028bd4545c8edbc14b4ed67769e92e3ef
+  data.tar.gz: 23ce3eab9360b27dd23732589dc3794bb6c6c8cfe6ca9bf289830265ad8697ce0a2779836c0b4ff37c2a5c3211dffaaf74e817e63d0bc96417ad62af8048e444

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+### 0.1.7
+
+* Added IntegrationHelpers to support client testing.
+* Updated methods for interfacing with Rails client app.
+* Changed route path added by the generator.
+
+### 0.1.6
+
+* Added default_class and class_whitelist config parameters.
+
+### 0.1.5
+
+* Updated validation to ensure the agent has completed registration to be considered valid.
+
 ### 0.1.4
 
 * Changed namespace from Passkeys::Rails to PasskeysRails

data/README.md

@@ -1,15 +1,38 @@
-[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=5)](https://badge.fury.io/rb/passkeys-rails)
+[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=7)](https://badge.fury.io/rb/passkeys-rails)
 [![Build Status](https://app.travis-ci.com/alliedcode/passkeys-rails.svg?branch=main)](https://travis-ci.org/alliedcode/passkeys-rails)
 [![codecov](https://codecov.io/gh/alliedcode/passkeys-rails/branch/main/graph/badge.svg?token=UHSNJDUL21)](https://codecov.io/gh/alliedcode/passkeys-rails)
 
 # PasskeysRails
-Devise is awesome, but we don't need all that UI/UX for PassKeys.  This gem is to make it easy to provide a back end that authenticates a mobile front end with PassKeys.
+
+Devise is awesome, but we don't need all that UI/UX for PassKeys.
+
+The purpose of this gem is to make it easy to provide a rails back end API that supports PassKey authentication.  It uses the [`webauthn`](https://github.com/w3c/webauthn) gem to do the cryptographic work and presents a simple API interface for passkey registration and authentication.
+
+The target use case for this gem is a mobile application that uses a rails based API service to manage resources.  The goal is to make it simple to register and authenticate users using passkeys from mobile applications in a rails API service.
+
 
 ## Usage
-rails passkeys-rails::install
-PasskeysRails maintains an Agent model and related Passeys.  If you have a user model, add `include PasskeysRails::Authenticatable` to your model and include the name of that class (e.g. "User") in the authenticatable_class param when calling the register API.
+
+**PasskeysRails** maintains an `Agent` model and related `Passkeys`.  If you have a user model, add `include PasskeysRails::Authenticatable` to your model and include the name of that class (e.g. `"User"`) in the `authenticatable_class` param when calling the register API or set the `PasskeysRails.default_class` to the name of that class.
+
+### Optionally providing a **"user"** model during registration
+
+**PasskeysRails** does not require that you supply your own model, but it's often useful to do so.  For example, if you have a User model that you would like to have created at registration, you can supply the model name in the `finishRegistration` API call.
+
+**PasskeysRails** supports multiple `"user"` models.  Whatever model name you supply will be created during a successful the `finishRegiration` API call. When created, it will be provided an opportunity to do any initialization at that time.
+
+There are two **PasskeysRails** configuration options related to this: `default_class` and `class_whitelist` - see below.
+
+#### `default_class`
+
+Configure `default_class` in `passkeys_rails.rb`.  Its value will be used during registration if none is provided in the API call.  The default value is `"User"`.  Since the `default_class` is just a default, it can be overridden in the `finishRegiration` API call to use a different model.  If no model is to be used by default, set it to nil.
+
+#### `class_whitelist`
+
+Configure `class_whitelist` in `passkeys_rails.rb`.  The default value is `nil`.  When `nil`, no whitelist will be applied. If it is non-nil, it should be an array of class names that are allowed during registration.  Supply an empty array to prevent **PasskeysRails** from attempting to create anything other than its own `PasskeysRails::Agent` during registration.
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -17,8 +40,9 @@ gem "passkeys_rails"
 ```
 
 And then execute:
+
 ```bash
-$ bundle
+$ bundle install
 ```
 
 Or install it yourself as:
@@ -26,22 +50,139 @@ Or install it yourself as:
 $ gem install passkeys_rails
 ```
 
-Depending on your application's configuration some manual setup may be required:
+Finally, execute:
+
+```bash
+$ rails generate passkeys_rails:install
+```
+
+This will add the `passkeys_rails.rb` configuration file, passkeys routes, and a couple of database migrations to your project.
+
+### Adding to an standard rails project
+
+1. Add `before_action :authenticate_passkey!`
+
+ To prevent access to controller actions, add `before_action :authenticate_passkey!`.  If an action is attempted without an authenticated entity, an error will be rendered in JSON with an :unauthorized result code.
+
+1. Use `current_agent` and `current_agent.authenticatable`
+
+ To access the currently authenticated entity, use `current_agent`.  If you associated the registration of the agent with one of your own models, use `current_agent.authenticatable`.  For example, if you associated the `User` class with the registration, `current_agent.authenticatable` will be a User object.
 
-  1. Add a before_action to all controllers that require authentication to use.
+1. Add `include PasskeysRails::Authenticatable` to model class(es)
 
-     For example:
+ If you have one or more classes that you want to use with authentication - e.g. a User class and an AdminUser class - add `include PasskeysRails::Authenticatable` to each of those classes.  That adds a `registered?` method that you can call on your model to determine if they are registerd with your service, and a `registering_with(params)` method that you can override to initialize attributes of your model when it is created during registration. `params` is a hash with params passed to the API when registering.  When called, your object has been built, but not yet saved.  Upon return, **PasskeysRails** will attempt to save your object before finishing registration.  If it is not valid, the registration will fail as well, returning the error error details to the caller.
 
-        before_action :authenticate_passkey!, except: [:index]
+### Adding to a Grape API rails project
 
-  2. Optionally include PasskeysRails::Authenticatable to the model(s) you are using as
-     your user model(s).  For example, the User model.
+1. Call `PasskeysRails.authenticate(request)` to authenticate the request.
 
-  3. See the reference mobile applications for how to use passkeys-rails for passkey
-     authentication.
+ Call `PasskeysRails.authenticate(request)` to get an object back that responds to `.success?` and `.failure?` as well as `.agent`, `.code`, and `.message`.
+
+ Alternatively, call `PasskeysRails.authenticate!(request)` from a helper in your base class.  It will raise a `PasskeysRails.Error` exception if the caller isn't authenticated.  You can catch the exception and render an appropriate error.  The exception contains the error code and message.
+
+1. Consider adding the following helpers to your base API class:
+
+```ruby
+  helpers do
+    # Authenticate the request and cache the result
+    def passkey
+      @passkey ||= PasskeysRails.authenticate(request)
+    end
+
+    # Raise an exception if the request is not authentic
+    def authenticate_passkey!
+      error!({ code: passkey.code, message: passkey.message }, :unauthorized) if passkey.failure?
+    end
+
+    # Return the Passkeys::Agent if authentic, else return nil
+    def current_agent
+      passkey.agent
+    end
+
+    # If you have set authenticatable to be a User, you can use this to access the user from Grape endpoint methods
+    def current_user
+      user = current_agent&.authenticatable
+      user.is_a?(User) ? user : nil # sanity check to be sure authenticatable is a User
+    end
+  end
+```
+
+ To prevent access to various endpoints, add `before_action :authenticate_passkey!` or call `authenticate_passkey!` from any method that requires authentication.  If an action is attempted without an authenticated entity, an error will be rendered in JSON with an :unauthorized result code.
+
+1. Use `current_agent` and `current_agent.authenticatable`
+
+ To access the currently authenticated entity, use `current_agent`.  If you associated the registration of the agent with one of your own models, use `current_agent.authenticatable`.  For example, if you associated the `User` class with the registration, `current_agent.authenticatable` will be a User object.
+
+### Authentication Failure
+
+1. In the event of authentication failure, PasskeysRails returns an error code and message.
+
+1. In a standard rails controller, the error code and message are rendered in JSON if `before_action :authenticate_passkey!` fails.
+
+1. In Grape, the error code and message are available in the result of the `PasskeysRails.authenticate(request)` method.
+
+1. From standard rails controllers, you can also access `passkey_authentication_result` to get the code and message.
+
+1. For `PasskeysRails.authenticate(request)` and `passkey_authentication_result`, the result is an object that respods to `.success?` and `.failure?`.
+ - When `.success?` is true (`.failure?` is false), the resources is authentic and it also responds to `.agent`, returning a PasskeysRails::Agent
+ - When `.success?` is false (`.failure?` is true), it responds to `.code` and `.message` to expose the error details.
+ - When `.code` is `:missing_token`, `.message` is **X-Auth header is required**, which means the caller didn't supply the auth header.
+ - When `.code` is `:invalid_token`, `.message` is **Invalid token - no agent exists with agent_id**, which means that the auth data is not valid.
+ - When `.code` is `:expired_token`, `.message` is **The token has expired**, which means that the token is valid, but expired, thuis it's not considered authentic.
+ - When `.code` is `:token_error`, `.message` is a description of the error.  This is a catch-all in the event we are unable to decode the token.
+
+ In the future, the intention is to have the `.code` value stay consistent even if the `.message` changes.  This also allows you to localize the messages as need using the code.
+
+### Test Helpers
+
+PasskeysRails includes some test helpers for integration tests.  In order to use them, you need to include the module in your test cases/specs.
+
+### Integration tests
+
+Integration test helpers are available by including the `PasskeysRails::IntegrationHelpers` module.
+
+```ruby
+class PostTests < ActionDispatch::IntegrationTest
+  include PasskeysRails::Test::IntegrationHelpers
+end
+```
+Now you can use the following `logged_in_headers` method in your integration tests.`
+
+```ruby
+  test 'authenticated users can see posts' do
+    user = User.create
+    get '/posts', headers: logged_in_headers('username-123', user)
+    assert_response :success
+  end
+```
+
+RSpec can include the `IntegrationHelpers` module in their `:feature` and `:request` specs.
+
+```ruby
+RSpec.configure do |config|
+  config.include PasskeysRails::Test::IntegrationHelpers, type: :feature
+  config.include PasskeysRails::Test::IntegrationHelpers, type: :request
+end
+```
+
+```ruby
+RSpec.describe 'Posts', type: :request do
+  let(:user) { User.create }
+  it "allows authenticated users to see posts" do
+    get '/posts', headers: logged_in_headers('username-123', user)
+    expect(response).to be_success
+  end
+end
+```
+
+### Mobile Application Integration
+
+**TODO**: Describe the APIs and point to the soon-to-be-created reference mobile applications for how to use **passkeys-rails** for passkey authentication.
 
 ## Contributing
-Contribution directions go here.
+
+Contact me if you'd like to contribute time, energy, etc. to this project.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/concerns/passkeys_rails/authentication.rb

@@ -9,22 +9,17 @@ module PasskeysRails
     end
 
     def current_agent
-      @current_agent ||= (request.headers['HTTP_X_AUTH'].present? &&
-                         passkey_authentication_result.success? &&
+      @current_agent ||= (passkey_authentication_result.success? &&
                          passkey_authentication_result.agent.registered? &&
                          passkey_authentication_result.agent) || nil
     end
 
     def authenticate_passkey!
-      return if current_agent.present?
-
-      raise PasskeysRails::Error.new(:authentication,
-                                     code: :unauthorized,
-                                     message: "You are not authorized to access this resource.")
+      @authenticate_passkey ||= PasskeysRails.authenticate!(request)
     end
 
     def passkey_authentication_result
-      @passkey_authentication_result ||= PasskeysRails::ValidateAuthToken.call(auth_token: request.headers['HTTP_X_AUTH'])
+      @passkey_authentication_result ||= PasskeysRails.authenticate(request)
     end
   end
 end

data/app/controllers/passkeys_rails/passkeys_controller.rb

@@ -11,7 +11,7 @@ module PasskeysRails
 
     def register
       result = PasskeysRails::FinishRegistration.call!(credential: attestation_credential_params.to_h,
-                                                       authenticatable_class:,
+                                                       authenticatable_info: authenticatable_info&.to_h,
                                                        username: session.dig(:passkeys_rails, :username),
                                                        challenge: session.dig(:passkeys_rails, :challenge))
 
@@ -43,8 +43,8 @@ module PasskeysRails
       credential.permit(:id, :rawId, :type, { response: %i[attestationObject clientDataJSON] })
     end
 
-    def authenticatable_class
-      params[:authenticatable_class]
+    def authenticatable_info
+      params.require[:authenticatable].permit(:class, :params) if params[:authenticatable].present?
     end
 
     def authentication_params

data/app/interactors/passkeys_rails/finish_registration.rb

@@ -3,7 +3,7 @@ module PasskeysRails
   class FinishRegistration
     include Interactor
 
-    delegate :credential, :username, :challenge, :authenticatable_class, to: :context
+    delegate :credential, :username, :challenge, :authenticatable_info, to: :context
 
     def call
       verify_credential!
@@ -40,25 +40,52 @@ module PasskeysRails
           context.fail! code: :passkey_error, message: e.message
         end
 
-        create_authenticatable! if authenticatable_class.present?
+        create_authenticatable! if aux_class_name.present?
       end
     end
 
-    def create_authenticatable!
-      klass = begin
-        authenticatable_class.constantize
-      rescue StandardError
-        context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{authenticatable_class}) is not defined")
-      end
+    def authenticatable_class
+      authenticatable_info && authenticatable_info[:class]
+    end
+
+    def authenticatable_params
+      authenticatable_info && authenticatable_info[:params]
+    end
+
+    def aux_class_name
+      @aux_class_name ||= authenticatable_class || PasskeysRails.default_class
+    end
+
+    def aux_class
+      whitelist = PasskeysRails.class_whitelist
 
-      begin
-        authenticatable = klass.create! do |obj|
-          obj.registering_with(agent) if obj.respond_to?(:registering_with)
+      @aux_class ||= begin
+        if whitelist.is_a?(Array)
+          unless whitelist.include?(aux_class_name)
+            context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not in the whitelist")
+          end
+        elsif whitelist.present?
+          context.fail!(code: :invalid_class_whitelist,
+                        message: "class_whitelist is invalid.  It should be nil or an array of zero or more class names.")
         end
-        agent.update!(authenticatable:)
-      rescue ActiveRecord::RecordInvalid => e
-        context.fail!(code: :record_invalid, message: e.message)
+
+        begin
+          aux_class_name.constantize
+        rescue StandardError
+          context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not defined")
+        end
+      end
+    end
+
+    def create_authenticatable!
+      authenticatable = aux_class.create! do |obj|
+        obj.agent = agent if obj.respond_to?(:agent=)
+        obj.registering_with(authenticatable_params) if obj.respond_to?(:registering_with)
       end
+
+      agent.update!(authenticatable:)
+    rescue ActiveRecord::RecordInvalid => e
+      context.fail!(code: :record_invalid, message: e.message)
     end
 
     def webauthn_credential

data/app/models/concerns/passkeys_rails/authenticatable.rb

@@ -5,11 +5,11 @@ module PasskeysRails
     extend ActiveSupport::Concern
 
     included do
-      has_one :agent, as: :authenticatable
+      has_one :agent, as: :authenticatable, class_name: "PasskeysRails::Agent"
 
       delegate :registered?, to: :agent, allow_nil: true
 
-      def registering_with(_agent)
+      def registering_with(_params)
         # initialize required attributes
       end
     end

data/lib/generators/passkeys_rails/USAGE

@@ -2,7 +2,7 @@ Description:
     Creates a PasskeysRails config file, updates the routes and adds migrations.
 
 Example:
-    bin/rails generate passkeys-rails:install
+    bin/rails generate passkeys_rails:install
 
     This will:
         create config/passkeys_rails.rb

data/lib/generators/passkeys_rails/install_generator.rb

@@ -5,14 +5,22 @@ module PasskeysRails
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
+      desc "Adds passkeys config file to your application."
       def copy_config
         template 'passkeys_rails_config.rb', "config/initializers/passkeys_rails.rb"
       end
 
+      desc "Adds passkeys routes to your application."
       def add_routes
-        route 'mount PasskeysRails::Engine => "/passkeys_rails"'
+        route 'mount PasskeysRails::Engine => "/passkeys"'
       end
 
+      desc "Copies migrations to your application."
+      def copy_migrations
+        rake("passkeys_rails:install:migrations")
+      end
+
+      desc "Displays readme during installation."
       def show_readme
         readme "README" if behavior == :invoke
       end

data/lib/generators/passkeys_rails/templates/passkeys_rails_config.rb

@@ -21,4 +21,28 @@ PasskeysRails.config do |c|
   # Default is 30 days
   #
   # c.auth_token_expires_in = 30.days
+
+  # Model to use when creating or authenticating a passkey.
+  # This can be overridden when calling the API, but if no
+  # value is supplied when calling the API, this value is used.
+  #
+  # If nil, there is no default, and if none is supplied when
+  # calling the API, no resource is created other than
+  # a PaskeysRails::Agent that is used to track the passkey.
+  #
+  # This library doesn't assume that there will only be one
+  # model, but it is a common use case, so setting the
+  # default_class simplifies the use of the API in that case.
+  #
+  # c.default_class = "User"
+
+  # By providing a class_whitelist, the API will require that
+  # any supplied class is in the whitelist.  If it is not, the
+  # auth API will return an error.  This prevents a caller from
+  # attempting to create an unintended records on registration.
+  # If nil, any model will be allowed.
+  # This should be an array of symbols or strings,
+  # for example: %w[User AdminUser]
+  #
+  # c.class_whitelist = nil
 end

data/lib/passkeys-rails.rb

@@ -4,6 +4,10 @@ require 'passkeys_rails/version'
 require_relative "generators/passkeys_rails/install_generator"
 
 module PasskeysRails
+  module Test
+    autoload :IntegrationHelpers, 'passkeys_rails/test/integration_helpers'
+  end
+
   # Secret used to encode the auth token.
   # Rails.application.secret_key_base is used if none is defined here.
   # Changing this value will invalidate all tokens that have been fetched
@@ -19,6 +23,50 @@ module PasskeysRails
   # Set it to 0 for no expiration (not recommended in production).
   mattr_accessor :auth_token_expires_in, default: 30.days
 
+  # Model to use when creating or authenticating a passkey.
+  # This can be overridden when calling the API, but if no
+  # value is supplied when calling the API, this value is used.
+  # If nil, there is no default, and if none is supplied when
+  # calling the API, no resource is created other than
+  # a PaskeysRails::Agent that is used to track the passkey.
+  #
+  # This library doesn't assume that there will only be one
+  # model, but it is a common use case, so setting the
+  # default_class simplifies the use of the API in that case.
+  mattr_accessor :default_class, default: "User"
+
+  # By providing a class_whitelist, the API will require that
+  # any supplied class is in the whitelist.  If it is not, the
+  # auth API will return an error.  This prevents a caller from
+  # attempting to create an unintended record on registration.
+  # If nil, any model will be allowed.
+  # If [], no model will be allowed.
+  # This should be an array of symbols or strings,
+  # for example: %w[User AdminUser]
+  mattr_accessor :class_whitelist, default: nil
+
+  # Returns an Interactor::Context that indicates if the request is authentic.
+  #
+  # .success? is true if authentic
+  # .agent is the Passkey::Agent on success
+  #
+  # .failure? is true if failed (just the opposite of .success?)
+  # .code is the error code on failure
+  # .message is the human readable error message on failure
+  def self.authenticate(request)
+    PasskeysRails::ValidateAuthToken.call(auth_token: request.headers['X-Auth'])
+  end
+
+  # Raises a PasskeysRails::Error exception if the request is not authentic.
+  def self.authenticate!(request)
+    auth = authenticate(request)
+    return if auth.success?
+
+    raise PasskeysRails::Error.new(:authentication,
+                                   code: auth.code,
+                                   message: auth.message)
+  end
+
   class << self
     def config
       yield self

data/lib/passkeys_rails/test/integration_helpers.rb

@@ -0,0 +1,46 @@
+module PasskeysRails
+  # PasskeysRails::Test::IntegrationHelpers is a helper module for facilitating
+  # authentication on Rails integration tests to bypass the required steps for
+  # signin in or signin out a record.
+  #
+  # Examples
+  #
+  #  class PostsTest < ActionDispatch::IntegrationTest
+  #    include PasskeysRails::Test::IntegrationHelpers
+  #
+  #    test 'authenticated users can see posts' do
+  #      get '/posts', headers: logged_in_headers('username-1')
+  #      assert_response :success
+  #    end
+  #  end
+  module Test
+    module IntegrationHelpers
+      def self.included(base)
+        base.class_eval do
+          setup :setup_integration_for_passkeys_rails
+          teardown :teardown_integration_for_passkeys_rails
+        end
+      end
+
+      def logged_in_headers(username, authenticatable = nil, headers: {})
+        @agent = Agent.create(username:, registered_at: Time.current, authenticatable:)
+        result = PasskeysRails::GenerateAuthToken.call(agent:)
+        raise result.message if result.failure?
+
+        headers.merge("X-Auth" => result.auth_token)
+      end
+
+      protected
+
+      attr_reader :agent
+
+      def setup_integration_for_passkeys_rails
+        # Nothing to do here
+      end
+
+      def teardown_integration_for_passkeys_rails
+        @agent&.destroy
+      end
+    end
+  end
+end

data/lib/passkeys_rails/version.rb

@@ -1,3 +1,3 @@
 module PasskeysRails
-  VERSION = "0.1.5".freeze
+  VERSION = "0.1.7".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: passkeys-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Troy Anderson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-24 00:00:00.000000000 Z
+date: 2023-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -378,6 +378,7 @@ files:
 - lib/passkeys-rails.rb
 - lib/passkeys_rails/engine.rb
 - lib/passkeys_rails/railtie.rb
+- lib/passkeys_rails/test/integration_helpers.rb
 - lib/passkeys_rails/version.rb
 - lib/tasks/passkeys_rails_tasks.rake
 homepage: https://github.com/alliedcode/passkeys-rails