passkeys-rails 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd944c1cfd019fb6abe5f0ec87383d1b2b60146b237eb78cc3836a2143947f57
-  data.tar.gz: 66533dd94392e42e01c1bea10002c3331db983a73d5270f32caa9f13a9f34707
+  metadata.gz: c6b2553d498c30365341aba0aad49eafd09c5b49dd5453bbad29c20a026ab39c
+  data.tar.gz: 795d362e15d977c47b5381a4fe5cc852cdd546a0fa8f81e5a5452343f2b4fa1e
 SHA512:
-  metadata.gz: df0a42e46f2dfe8f414d3772215836b6f926a5421c2a7fde9dfbdaae13d4b04effbcc066e3278432b6936770e3822f8a2cf4dcbb44a2d23da48f8e6626b20f8a
-  data.tar.gz: 6d9acca7962dede01d787e961e585736ab4ab1c18d685031ba9409344636c96433282b45ef169101a64d6b6835144dcf9cde95dc5e1bc41dfb1ff2390034a1af
+  metadata.gz: 15694fd664f6b60343ede055acfefdfef0d8378ffe386420e7cd5d996920fe19a9321ac1148f3e22605b85a8486cbd1f56999167a84be33f9acf950ea0e5e722
+  data.tar.gz: b6f224af15ee0feb2489c786eefe68293d4854b43b7dcf3a2d17dea4514497cdd5df5f80bd5941972918b4c05864529c62bbe694c09ff58540a87529216bf8f3

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+### 0.1.2
+
+* Restructured lib directory.
+
+* Fixed naming convention for gem/gemspec.
+
+* Fixed exception handling.
+
+### 0.1.1
+
+* Fixed dependency
+
+### 0.1.0
+
+* Initial release - looking for feedback

data/README.md

@@ -1,12 +1,13 @@
+[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg)](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
+# Passkeys::Rails
 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.
 
 ## 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.
+Passkeys::Rails maintains an Agent model and related Passeys.  If you have a user model, add `include Passkeys::Rails::Authenticatable` to your model and include the name of that class (e.g. "User") in the authenticatable_class param when calling the register API.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -25,6 +26,20 @@ Or install it yourself as:
 $ gem install passkeys_rails
 ```
 
+Depending on your application's configuration some manual setup may be required:
+
+  1. Add a before_action to all controllers that require authentication to use.
+
+     For example:
+
+        before_action :authenticate_passkey!, except: [:index]
+
+  2. Optionally include Passkeys::Rails::Authenticatable to the model(s) you are using as
+     your user model(s).  For example, the User model.
+
+  3. See the reference mobile applications for how to use passkeys-rails for passkey
+     authentication.
+
 ## Contributing
 Contribution directions go here.
 

data/app/controllers/passkeys/rails/application_controller.rb

@@ -0,0 +1,24 @@
+module Passkeys
+  module Rails
+    class ApplicationController < ActionController::Base
+      rescue_from ::Interactor::Failure, with: :handle_interactor_failure
+      rescue_from ActionController::ParameterMissing, with: :handle_missing_parameter
+
+      protected
+
+      def handle_missing_parameter(error)
+        render_error(:authentication, 'missing_parameter', error.message)
+      end
+
+      def handle_interactor_failure(failure)
+        render_error(:authentication, failure.context.code, failure.context.message)
+      end
+
+      private
+
+      def render_error(context, code, message, status: :unprocessable_entity)
+        render json: { error: { context:, code:, message: } }, status:
+      end
+    end
+  end
+end

data/app/controllers/passkeys/rails/passkeys_controller.rb

@@ -0,0 +1,63 @@
+module Passkeys
+  module Rails
+    class PasskeysController < ApplicationController
+      def challenge
+        result = Passkeys::Rails::BeginChallenge.call!(username: challenge_params[:username])
+
+        # Store the challenge so we can verify the future register or authentication request
+        session[:passkeys_rails] = result.session_data
+
+        render json: result.response.as_json
+      end
+
+      def register
+        result = Passkeys::Rails::FinishRegistration.call!(credential: attestation_credential_params.to_h,
+                                                           authenticatable_class:,
+                                                           username: session.dig(:passkeys_rails, :username),
+                                                           challenge: session.dig(:passkeys_rails, :challenge))
+
+        render json: { username: result.username, auth_token: result.auth_token }
+      end
+
+      def authenticate
+        result = Passkeys::Rails::FinishAuthentication.call!(credential: authentication_params.to_h,
+                                                             challenge: session.dig(:passkeys_rails, :challenge))
+
+        render json: { username: result.username, auth_token: result.auth_token }
+      end
+
+      def refresh
+        result = Passkeys::Rails::RefreshToken.call!(token: refresh_params[:auth_token])
+        render json: { username: result.username, auth_token: result.auth_token }
+      end
+
+      protected
+
+      def challenge_params
+        params.permit(:username)
+      end
+
+      def attestation_credential_params
+        credential = params.require(:credential)
+        credential.require(%i[id rawId type response])
+        credential.require(:response).require(%i[attestationObject clientDataJSON])
+        credential.permit(:id, :rawId, :type, { response: %i[attestationObject clientDataJSON] })
+      end
+
+      def authenticatable_class
+        params[:authenticatable_class]
+      end
+
+      def authentication_params
+        params.require(%i[id rawId type response])
+        params.require(:response).require(%i[authenticatorData clientDataJSON signature userHandle])
+        params.permit(:id, :rawId, :type, { response: %i[authenticatorData clientDataJSON signature userHandle] })
+      end
+
+      def refresh_params
+        params.require(:auth_token)
+        params.permit(:auth_token)
+      end
+    end
+  end
+end

data/app/models/concerns/passkeys/rails/authenticatable.rb

@@ -0,0 +1,19 @@
+require 'active_support/concern'
+
+module Passkeys
+  module Rails
+    module Authenticatable
+      extend ActiveSupport::Concern
+
+      included do
+        has_one :agent, as: :authenticatable
+
+        delegate :registered?, to: :agent, allow_nil: true
+
+        def registering_with(_agent)
+          # initialize required attributes
+        end
+      end
+    end
+  end
+end

data/app/models/passkeys/rails/agent.rb

@@ -0,0 +1,17 @@
+module Passkeys
+  module Rails
+    class Agent < ApplicationRecord
+      belongs_to :authenticatable, polymorphic: true, optional: true
+      has_many :passkeys
+
+      scope :registered, -> { where.not registered_at: nil }
+      scope :unregistered, -> { where registered_at: nil }
+
+      validates :username, presence: true, uniqueness: true
+
+      def registered?
+        registered_at.present?
+      end
+    end
+  end
+end

data/app/models/passkeys/rails/application_record.rb

@@ -0,0 +1,7 @@
+module Passkeys
+  module Rails
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/passkeys/rails/error.rb

@@ -0,0 +1,16 @@
+module Passkeys
+  module Rails
+    class Error < StandardError
+      attr_reader :hash
+
+      def initialize(message, hash = {})
+        @hash = hash
+        super(message)
+      end
+
+      def to_h
+        { error: hash.merge(context: message) }
+      end
+    end
+  end
+end

data/app/models/passkeys/rails/passkey.rb

@@ -0,0 +1,10 @@
+module Passkeys
+  module Rails
+    class Passkey < ApplicationRecord
+      belongs_to :agent
+      validates :identifier, presence: true, uniqueness: true
+      validates :public_key, presence: true
+      validates :sign_count, presence: true
+    end
+  end
+end

data/config/routes.rb

@@ -1,4 +1,4 @@
-PasskeysRails::Engine.routes.draw do
+Passkeys::Rails::Engine.routes.draw do
   post 'passkeys/challenge'
   post 'passkeys/register'
   post 'passkeys/authenticate'

data/lib/generators/passkeys_rails/USAGE

@@ -1,5 +1,5 @@
 Description:
-    Creates a PasskeysRails config file, updates the routes and adds migrations.
+    Creates a Passkeys::Rails config file, updates the routes and adds migrations.
 
 Example:
     bin/rails generate passkeys-rails:install

data/lib/generators/passkeys_rails/install_generator.rb

@@ -1,20 +1,22 @@
 require 'rails/generators'
 
-module PasskeysRails
-  module Generators
-    class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
+module Passkeys
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
 
-      def copy_config
-        template 'passkeys_rails_config.rb', "config/initializers/passkeys_rails.rb"
-      end
+        def copy_config
+          template 'passkeys_rails_config.rb', "config/initializers/passkeys_rails.rb"
+        end
 
-      def add_routes
-        route 'mount PasskeysRails::Engine => "/passkeys_rails"'
-      end
+        def add_routes
+          route 'mount Passkeys::Rails::Engine => "/passkeys_rails"'
+        end
 
-      def show_readme
-        readme "README" if behavior == :invoke
+        def show_readme
+          readme "README" if behavior == :invoke
+        end
       end
     end
   end

data/lib/generators/passkeys_rails/templates/README

@@ -6,9 +6,9 @@ Depending on your application's configuration some manual setup may be required:
 
      For example:
 
-        before_action :authitencate_passkey!, except: [:index]
+        before_action :authenticate_passkey!, except: [:index]
 
-  2. Optionally include PasskeysRails::Authenticatable to the model(s) you are using as
+  2. Optionally include Passkeys::Rails::Authenticatable to the model(s) you are using as
      your user model(s).  For example, the User model.
 
   3. See the reference mobile applications for how to use passkeys-rails for passkey

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

@@ -1,6 +1,6 @@
-require 'passkeys_rails'
+require 'passkeys-rails'
 
-PasskeysRails.config do |c|
+Passkeys::Rails.config do |c|
   # Secret used to encode the auth token.
   # Changing this value will invalidate all tokens that have been fetched
   # through the API.

data/lib/passkeys/rails/controllers/helpers.rb

@@ -0,0 +1,33 @@
+module Passkeys
+  module Rails
+    module Controllers
+      module Helpers
+        extend ActiveSupport::Concern
+
+        included do
+          rescue_from Passkeys::Rails::Error do |e|
+            render json: e.to_h, status: :unauthorized
+          end
+        end
+
+        def current_agent
+          return nil if request.headers['HTTP_X_AUTH'].blank?
+
+          @current_agent ||= validated_auth_token&.success? && validated_auth_token&.agent
+        end
+
+        def authenticate_passkey!
+          return if validated_auth_token.success?
+
+          raise Passkeys::Rails::Error.new(:authentication,
+                                           code: :unauthorized,
+                                           message: "You are not authorized to access this resource.")
+        end
+
+        def validated_auth_token
+          @validated_auth_token ||= Passkeys::Rails::ValidateAuthToken.call(auth_token: request.headers['HTTP_X_AUTH'])
+        end
+      end
+    end
+  end
+end

data/lib/passkeys/rails/engine.rb

@@ -0,0 +1,44 @@
+require "rails"
+require "active_support/core_ext/numeric/time"
+require "active_support/dependencies"
+
+require "interactor"
+require "jwt"
+require "webauthn"
+
+require_relative 'controllers/helpers'
+require_relative "interactors/begin_authentication"
+require_relative "interactors/begin_challenge"
+require_relative "interactors/begin_registration"
+require_relative "interactors/finish_authentication"
+require_relative "interactors/finish_registration"
+require_relative "interactors/generate_auth_token"
+require_relative "interactors/refresh_token"
+require_relative "interactors/validate_auth_token"
+
+module Passkeys
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Passkeys::Rails
+
+      config.generators do |g|
+        g.test_framework :rspec
+        g.fixture_replacement :factory_bot
+        g.factory_bot dir: 'spec/factories'
+        g.assets false
+        g.helper false
+      end
+
+      # Include helpers
+      initializer "passkeys-rails.helpers" do
+        ActiveSupport.on_load(:action_controller_base) do
+          include Passkeys::Rails::Controllers::Helpers
+        end
+
+        ActiveSupport.on_load(:action_controller_api) do
+          include Passkeys::Rails::Controllers::Helpers
+        end
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/begin_authentication.rb

@@ -0,0 +1,11 @@
+module Passkeys
+  module Rails
+    class BeginAuthentication
+      include Interactor
+
+      def call
+        context.options = WebAuthn::Credential.options_for_get
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/begin_challenge.rb

@@ -0,0 +1,37 @@
+module Passkeys
+  module Rails
+    class BeginChallenge
+      include Interactor
+
+      delegate :username, to: :context
+
+      def call
+        result = generate_challenge!
+
+        options = result.options
+
+        context.response = options
+        context.session_data = session_data(options)
+      rescue Interactor::Failure => e
+        context.fail! code: e.context.code, message: e.context.message
+      end
+
+      private
+
+      def generate_challenge!
+        if username.present?
+          BeginRegistration.call!(username:)
+        else
+          BeginAuthentication.call!
+        end
+      end
+
+      def session_data(options)
+        {
+          username:,
+          challenge: WebAuthn.standard_encoder.encode(options.challenge)
+        }
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/begin_registration.rb

@@ -0,0 +1,25 @@
+module Passkeys
+  module Rails
+    class BeginRegistration
+      include Interactor
+
+      delegate :username, to: :context
+
+      def call
+        agent = create_unregistered_agent
+
+        context.options = WebAuthn::Credential.options_for_create(user: { id: agent.webauthn_identifier, name: agent.username })
+      end
+
+      private
+
+      def create_unregistered_agent
+        agent = Agent.create(username:, webauthn_identifier: WebAuthn.generate_user_id)
+
+        context.fail!(code: :validation_errors, message: agent.errors.full_messages.to_sentence) unless agent.valid?
+
+        agent
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/finish_authentication.rb

@@ -0,0 +1,55 @@
+# Finish authentication ceremony
+module Passkeys
+  module Rails
+    class FinishAuthentication
+      include Interactor
+
+      delegate :credential, :challenge, to: :context
+
+      def call
+        verify_credential!
+
+        context.username = agent.username
+        context.auth_token = GenerateAuthToken.call!(agent:).auth_token
+      rescue Interactor::Failure => e
+        context.fail! code: e.context.code, message: e.context.message
+      end
+
+      private
+
+      def verify_credential!
+        webauthn_credential.verify(
+          challenge,
+          public_key: passkey.public_key,
+          sign_count: passkey.sign_count
+        )
+
+        passkey.update!(sign_count: webauthn_credential.sign_count)
+        agent.update!(last_authenticated_at: Time.current)
+      rescue WebAuthn::SignCountVerificationError
+        # Cryptographic verification of the authenticator data succeeded, but the signature counter was less than or equal
+        # to the stored value. This can have several reasons and depending on your risk tolerance you can choose to fail or
+        # pass authentication. For more information see https://www.w3.org/TR/webauthn/#sign-counter
+      rescue WebAuthn::Error => e
+        context.fail!(code: :webauthn_error, message: e.message)
+      end
+
+      def webauthn_credential
+        @webauthn_credential ||= WebAuthn::Credential.from_get(credential)
+      end
+
+      def passkey
+        @passkey ||= begin
+          passkey = Passkey.find_by(identifier: webauthn_credential.id)
+          context.fail!(code: :passkey_not_found, message: "Unable to find the specified passkey") if passkey.blank?
+
+          passkey
+        end
+      end
+
+      def agent
+        passkey.agent
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/finish_registration.rb

@@ -0,0 +1,79 @@
+# Finish registration ceremony
+module Passkeys
+  module Rails
+    class FinishRegistration
+      include Interactor
+
+      delegate :credential, :username, :challenge, :authenticatable_class, to: :context
+
+      def call
+        verify_credential!
+        store_passkey_and_register_agent!
+
+        context.username = agent.username
+        context.auth_token = GenerateAuthToken.call!(agent:).auth_token
+      rescue Interactor::Failure => e
+        context.fail! code: e.context.code, message: e.context.message
+      end
+
+      private
+
+      def verify_credential!
+        webauthn_credential.verify(challenge)
+      rescue WebAuthn::Error => e
+        context.fail!(code: :webauthn_error, message: e.message)
+      rescue StandardError => e
+        context.fail!(code: :error, message: e.message)
+      end
+
+      def store_passkey_and_register_agent!
+        agent.transaction do
+          begin
+            # Store Credential ID, Credential Public Key and Sign Count for future authentications
+            agent.passkeys.create!(
+              identifier: webauthn_credential.id,
+              public_key: webauthn_credential.public_key,
+              sign_count: webauthn_credential.sign_count
+            )
+
+            agent.update! registered_at: Time.current
+          rescue StandardError => e
+            context.fail! code: :passkey_error, message: e.message
+          end
+
+          create_authenticatable! if authenticatable_class.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
+
+        begin
+          authenticatable = klass.create! do |obj|
+            obj.registering_with(agent) if obj.respond_to?(:registering_with)
+          end
+          agent.update!(authenticatable:)
+        rescue ActiveRecord::RecordInvalid => e
+          context.fail!(code: :record_invalid, message: e.message)
+        end
+      end
+
+      def webauthn_credential
+        @webauthn_credential ||= WebAuthn::Credential.from_create(credential)
+      end
+
+      def agent
+        @agent ||= begin
+          agent = Agent.find_by(username:)
+          context.fail!(code: :agent_not_found, message: "Agent not found for session value: \"#{username}\"") if agent.blank?
+
+          agent
+        end
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/generate_auth_token.rb

@@ -0,0 +1,29 @@
+module Passkeys
+  module Rails
+    class GenerateAuthToken
+      include Interactor
+
+      delegate :agent, to: :context
+
+      def call
+        context.auth_token = generate_auth_token
+      end
+
+      private
+
+      def generate_auth_token
+        JWT.encode(jwt_payload,
+                   Passkeys::Rails.auth_token_secret,
+                   Passkeys::Rails.auth_token_algorithm)
+      end
+
+      def jwt_payload
+        expiration = (Time.current + Passkeys::Rails.auth_token_expires_in).to_i
+
+        payload = { agent_id: agent.id }
+        payload[:exp] = expiration unless expiration.zero?
+        payload
+      end
+    end
+  end
+end

data/lib/passkeys/rails/interactors/refresh_token.rb

@@ -0,0 +1,19 @@
+# Finish authentication ceremony
+module Passkeys
+  module Rails
+    class RefreshToken
+      include Interactor
+
+      delegate :token, to: :context
+
+      def call
+        agent = ValidateAuthToken.call!(auth_token: token).agent
+
+        context.username = agent.username
+        context.auth_token = GenerateAuthToken.call!(agent:).auth_token
+      rescue Interactor::Failure => e
+        context.fail! code: e.context.code, message: e.context.message
+      end
+    end
+  end
+end