passkeys-rails 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6b2553d498c30365341aba0aad49eafd09c5b49dd5453bbad29c20a026ab39c
-  data.tar.gz: 795d362e15d977c47b5381a4fe5cc852cdd546a0fa8f81e5a5452343f2b4fa1e
+  metadata.gz: 2eb3101d4ecba95639b4cc95adfa6a86939b7bdc3e6db0e3c26ed9e154d9fa97
+  data.tar.gz: 86cc744ced315cb5a662743f2cbf44fa20a05f7fbe444103b62a82281b009edd
 SHA512:
-  metadata.gz: 15694fd664f6b60343ede055acfefdfef0d8378ffe386420e7cd5d996920fe19a9321ac1148f3e22605b85a8486cbd1f56999167a84be33f9acf950ea0e5e722
-  data.tar.gz: b6f224af15ee0feb2489c786eefe68293d4854b43b7dcf3a2d17dea4514497cdd5df5f80bd5941972918b4c05864529c62bbe694c09ff58540a87529216bf8f3
+  metadata.gz: f2b55ac5a4aea2f969ab32cff126f6cab53f2a0b819a998668d58b794231a4f6ca378247af0e2561fbf0062760ea0724641c36b4915c2bd2a9f24aedf2909a23
+  data.tar.gz: 115f5c9c098da302f13d45e6871ae0152a8bd454d4d5281effc29afcc7e1dfacf0b838322bb55ff5f9b17caf2f846917e1596c0f8e4fc8a525bf710e986e7a5f

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+### 0.1.4
+
+* Changed namespace from Passkeys::Rails to PasskeysRails
+
+### 0.1.3
+
+* More restructuring and fixed issue where autoloading failed
+  during client app initialization.
+
 ### 0.1.2
 
 * Restructured lib directory.

data/README.md

@@ -1,13 +1,13 @@
-[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg)](https://badge.fury.io/rb/passkeys-rails)
+[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=4)](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)
 
-# 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.
 
 ## Usage
 rails passkeys-rails::install
-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.
+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.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -34,7 +34,7 @@ Depending on your application's configuration some manual setup may be required:
 
         before_action :authenticate_passkey!, except: [:index]
 
-  2. Optionally include Passkeys::Rails::Authenticatable to the model(s) you are using as
+  2. Optionally include PasskeysRails::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/app/controllers/concerns/passkeys_rails/authentication.rb

@@ -0,0 +1,29 @@
+module PasskeysRails
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from PasskeysRails::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 PasskeysRails::Error.new(:authentication,
+                                     code: :unauthorized,
+                                     message: "You are not authorized to access this resource.")
+    end
+
+    def validated_auth_token
+      @validated_auth_token ||= PasskeysRails::ValidateAuthToken.call(auth_token: request.headers['HTTP_X_AUTH'])
+    end
+  end
+end

data/app/controllers/passkeys_rails/application_controller.rb

@@ -0,0 +1,22 @@
+module PasskeysRails
+  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

data/app/controllers/passkeys_rails/passkeys_controller.rb

@@ -0,0 +1,61 @@
+module PasskeysRails
+  class PasskeysController < ApplicationController
+    def challenge
+      result = PasskeysRails::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 = PasskeysRails::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 = PasskeysRails::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 = PasskeysRails::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

data/app/interactors/passkeys_rails/begin_authentication.rb

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

data/app/interactors/passkeys_rails/begin_challenge.rb

@@ -0,0 +1,35 @@
+module PasskeysRails
+  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

data/app/interactors/passkeys_rails/begin_registration.rb

@@ -0,0 +1,23 @@
+module PasskeysRails
+  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

data/app/interactors/passkeys_rails/finish_authentication.rb

@@ -0,0 +1,53 @@
+# Finish authentication ceremony
+module PasskeysRails
+  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

data/app/interactors/passkeys_rails/finish_registration.rb

@@ -0,0 +1,77 @@
+# Finish registration ceremony
+module PasskeysRails
+  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

data/app/interactors/passkeys_rails/generate_auth_token.rb

@@ -0,0 +1,27 @@
+module PasskeysRails
+  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,
+                 PasskeysRails.auth_token_secret,
+                 PasskeysRails.auth_token_algorithm)
+    end
+
+    def jwt_payload
+      expiration = (Time.current + PasskeysRails.auth_token_expires_in).to_i
+
+      payload = { agent_id: agent.id }
+      payload[:exp] = expiration unless expiration.zero?
+      payload
+    end
+  end
+end

data/app/interactors/passkeys_rails/refresh_token.rb

@@ -0,0 +1,17 @@
+# Finish authentication ceremony
+module PasskeysRails
+  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

data/app/interactors/passkeys_rails/validate_auth_token.rb

@@ -0,0 +1,33 @@
+module PasskeysRails
+  class ValidateAuthToken
+    include Interactor
+
+    delegate :auth_token, to: :context
+
+    def call
+      context.fail!(code: :missing_token, message: "X-Auth header is required") if auth_token.blank?
+
+      context.agent = fetch_agent
+    end
+
+    private
+
+    def fetch_agent
+      agent = Agent.find_by(id: payload['agent_id'])
+      context.fail!(code: :invalid_token, message: "Invalid token - no agent exists with agent_id") if agent.blank?
+
+      agent
+    end
+
+    def payload
+      JWT.decode(auth_token,
+                 PasskeysRails.auth_token_secret,
+                 true,
+                 { required_claims: %w[exp agent_id], algorithm: PasskeysRails.auth_token_algorithm }).first
+    rescue JWT::ExpiredSignature
+      context.fail!(code: :expired_token, message: "The token has expired")
+    rescue StandardError => e
+      context.fail!(code: :token_error, message: e.message)
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+require 'active_support/concern'
+
+module PasskeysRails
+  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

data/app/models/passkeys_rails/agent.rb

@@ -0,0 +1,15 @@
+module PasskeysRails
+  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

data/app/models/passkeys_rails/application_record.rb

@@ -0,0 +1,5 @@
+module PasskeysRails
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/passkeys_rails/error.rb

@@ -0,0 +1,14 @@
+module PasskeysRails
+  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

data/app/models/passkeys_rails/passkey.rb

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

data/config/initializers/application_controller.rb

@@ -0,0 +1,12 @@
+# These should be autoloaded, but if these aren't required here, apps using this
+# gem will throw an exception that PasskeysRails::Authentication can't be found
+require_relative '../../app/controllers/concerns/passkeys_rails/authentication'
+require_relative '../../app/models/passkeys_rails/error'
+
+class ActionController::Base
+  include PasskeysRails::Authentication
+end
+
+class ActionController::API
+  include PasskeysRails::Authentication
+end

data/config/routes.rb

@@ -1,4 +1,4 @@
-Passkeys::Rails::Engine.routes.draw do
+PasskeysRails::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 Passkeys::Rails config file, updates the routes and adds migrations.
+    Creates a PasskeysRails config file, updates the routes and adds migrations.
 
 Example:
     bin/rails generate passkeys-rails:install

data/lib/generators/passkeys_rails/install_generator.rb

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

data/lib/generators/passkeys_rails/templates/README

@@ -8,7 +8,7 @@ Depending on your application's configuration some manual setup may be required:
 
         before_action :authenticate_passkey!, except: [:index]
 
-  2. Optionally include Passkeys::Rails::Authenticatable to the model(s) you are using as
+  2. Optionally include PasskeysRails::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'
 
-Passkeys::Rails.config do |c|
+PasskeysRails.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.rb

@@ -1,36 +1,34 @@
 # rubocop:disable Naming/FileName
-require 'passkeys/rails/engine'
-require 'passkeys/rails/version'
+require 'passkeys_rails/engine'
+require 'passkeys_rails/version'
 require_relative "generators/passkeys_rails/install_generator"
 
-module Passkeys
-  module Rails
-    # 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
-    # through the API.
-    mattr_accessor(:auth_token_secret)
+module PasskeysRails
+  # 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
+  # through the API.
+  mattr_accessor(:auth_token_secret)
 
-    # Algorithm used to generate the auth token.
-    # Changing this value will invalidate all tokens that have been fetched
-    # through the API.
-    mattr_accessor :auth_token_algorithm, default: "HS256"
+  # Algorithm used to generate the auth token.
+  # Changing this value will invalidate all tokens that have been fetched
+  # through the API.
+  mattr_accessor :auth_token_algorithm, default: "HS256"
 
-    # How long the auth token is valid before requiring a refresh or new login.
-    # Set it to 0 for no expiration (not recommended in production).
-    mattr_accessor :auth_token_expires_in, default: 30.days
+  # How long the auth token is valid before requiring a refresh or new login.
+  # Set it to 0 for no expiration (not recommended in production).
+  mattr_accessor :auth_token_expires_in, default: 30.days
 
-    class << self
-      def config
-        yield self
-      end
+  class << self
+    def config
+      yield self
     end
-
-    require 'passkeys/rails/railtie' if defined?(Rails)
   end
+
+  require 'passkeys_rails/railtie' if defined?(Rails)
 end
 
 ActiveSupport.on_load(:before_initialize) do
-  Passkeys::Rails.auth_token_secret ||= Rails.application.secret_key_base
+  PasskeysRails.auth_token_secret ||= Rails.application.secret_key_base
 end
 # rubocop:enable Naming/FileName