passkeys-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d6b32ba5bcfa9553687bb70a01ba4e1b9211ab50336e62f3f7eae7033c3f689
-  data.tar.gz: e53cc11ffec79936ec74319fb1ec6d47cd74d67f4f56ff0c2d234abf8800b1f3
+  metadata.gz: afbb635c3ddfd36d60bccbf936e2a67e091a6bb15822683c9c1db050cdd49909
+  data.tar.gz: c9ef1cf6d9e9f5a760037efb831b856dbf706c0860fbf945eadd616c37cb297d
 SHA512:
-  metadata.gz: 87cb708335cfae465b142633dc829c92ac16c4d9d958807cbb682caf455ca18e2b13a24ad30b1bb3020f3493b6dd924151269eb37ba2eaeb09508d5b350a9572
-  data.tar.gz: 04fcd5259c6fe2b1d06f289254817fc1baee73e5d7c7d2aee3476a2155e02e2cb4c40c02deab4285a602bbe9c51806a3e90c5f15ed2b3de928ca9843b0f9fd14
+  metadata.gz: 92e7f2a72715c7c4b313d57f7dc1c928cf334375fcdd28fc104f86721562b45484220234e8e5924106fce344e94d95f9cb7e29d0d6879e4ac73451e7a1a17915
+  data.tar.gz: 686d6a95cec8274eaadd3fa1555a89f0e1554bc248c1f30eca1ac253933a158e8d12e08bcd74e53b42cbe33a9e0a1630ed14d1ce3a7205a2fe289366d3cbe2c3

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+### 0.3.0
+
+* Added debug_register endpoint.
+* Fixed authenticatable_params for register enpoint.
+* Added notifications to certain controller actions.
+* Improved spec error helper.
+
+### 0.2.1
+
+Added ability to pass either the auth token string or a request with one in the header to authenticate methods.
+
 ### 0.2.0
 
 * Added passkeys/debug_login functionality.

data/README.md

@@ -1,4 +1,4 @@
-[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=7)](https://badge.fury.io/rb/passkeys-rails)
+[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=0.2.1)](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)
 
@@ -56,7 +56,7 @@ Finally, execute:
 $ 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.
+This will add the `config/initializers/passkeys_rails.rb` configuration file, passkeys routes, and a couple of database migrations to your project.
 
 ### Adding to an standard rails project
 
@@ -113,6 +113,41 @@ This will add the `passkeys_rails.rb` configuration file, passkeys routes, and a
 
  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.
 
+### Notifications
+
+Certain actions trigger notifications that can be subscribed.  See `subscribe` in `passkeys_rails.rb`.
+
+#### Events
+
+- `:did_register ` - a new agent has registered
+
+- `:did_authenticate` - an agent has been authenticated
+
+- `:did_refresh` - an agent's auth token has been refreshed
+
+A convenient place to set these up in is in `passkeys_rails.rb`
+
+```ruby
+PasskeysRails.config do |c|
+  c.subscribe(:did_register) do |event, agent, request|
+    # do something with the agent and/or request
+  end
+
+  c.subscribe(:did_authenticate) do |event, agent, request|
+    # do something with the agent and/or request
+  end
+end
+```
+
+Subscriptions can also be done elsewhere as subscribe is a PasskeysRails class method.
+
+```ruby
+PasskeysRails.subscribe(:did_register) do |event, agent, request|
+  # do something with the agent and/or request
+end
+```
+
+
 ### Authentication Failure
 
 1. In the event of authentication failure, PasskeysRails returns an error code and message.

data/app/controllers/passkeys_rails/application_controller.rb

@@ -1,10 +1,15 @@
 module PasskeysRails
   class ApplicationController < ActionController::Base
+    rescue_from StandardError, with: :handle_standard_error
     rescue_from ::Interactor::Failure, with: :handle_interactor_failure
     rescue_from ActionController::ParameterMissing, with: :handle_missing_parameter
 
     protected
 
+    def handle_standard_error(error)
+      render_error(:authentication, 'error', error.message.truncate(512), status: 500)
+    end
+
     def handle_missing_parameter(error)
       render_error(:authentication, 'missing_parameter', error.message)
     end

data/app/controllers/passkeys_rails/passkeys_controller.rb

@@ -1,5 +1,8 @@
 module PasskeysRails
   class PasskeysController < ApplicationController
+    skip_before_action :verify_authenticity_token
+    wrap_parameters false
+
     def challenge
       result = PasskeysRails::BeginChallenge.call!(username: challenge_params[:username])
 
@@ -11,23 +14,30 @@ module PasskeysRails
 
     def register
       result = PasskeysRails::FinishRegistration.call!(credential: attestation_credential_params.to_h,
-                                                       authenticatable_info: authenticatable_info&.to_h,
+                                                       authenticatable_info: authenticatable_params&.to_h,
                                                        username: session.dig(:passkeys_rails, :username),
                                                        challenge: session.dig(:passkeys_rails, :challenge))
 
-      render json: { username: result.username, auth_token: result.auth_token }
+      broadcast(:did_register, agent: result.agent)
+
+      render json: auth_response(result)
     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 }
+      broadcast(:did_authenticate, agent: result.agent)
+
+      render json: auth_response(result)
     end
 
     def refresh
       result = PasskeysRails::RefreshToken.call!(token: refresh_params[:auth_token])
-      render json: { username: result.username, auth_token: result.auth_token }
+
+      broadcast(:did_refresh, agent: result.agent)
+
+      render json: auth_response(result)
     end
 
     # This action exists to allow easier mobile app debugging as it may not
@@ -36,11 +46,31 @@ module PasskeysRails
     # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
     def debug_login
       result = PasskeysRails::DebugLogin.call!(username: debug_login_params[:username])
-      render json: { username: result.username, auth_token: result.auth_token }
+
+      broadcast(:did_authenticate, agent: result.agent)
+
+      render json: auth_response(result)
+    end
+
+    # This action exists to allow easier mobile app debugging as it may not
+    # be possible to acess Passkey functionality in mobile simulators.
+    # It is only routable if DEBUG_LOGIN_REGEX is set in the server environment.
+    # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
+    def debug_register
+      result = PasskeysRails::DebugRegister.call!(username: debug_login_params[:username],
+                                                  authenticatable_info: authenticatable_params&.to_h)
+
+      broadcast(:did_register, agent: result.agent)
+
+      render json: auth_response(result)
     end
 
     protected
 
+    def auth_response(result)
+      { username: result.username, auth_token: result.auth_token }
+    end
+
     def challenge_params
       params.permit(:username)
     end
@@ -52,8 +82,8 @@ module PasskeysRails
       credential.permit(:id, :rawId, :type, { response: %i[attestationObject clientDataJSON] })
     end
 
-    def authenticatable_info
-      params.require[:authenticatable].permit(:class, :params) if params[:authenticatable].present?
+    def authenticatable_params
+      params.require(:authenticatable).permit(:class, params: {}) if params[:authenticatable].present?
     end
 
     def authentication_params
@@ -71,5 +101,9 @@ module PasskeysRails
       params.require(:username)
       params.permit(:username)
     end
+
+    def broadcast(event_name, agent:)
+      ActiveSupport::Notifications.instrument("passkeys_rails.#{event_name}", { agent:, request: })
+    end
   end
 end

data/app/interactors/passkeys_rails/debug_login.rb

@@ -5,6 +5,7 @@
 module PasskeysRails
   class DebugLogin
     include Interactor
+    include Debuggable
 
     delegate :username, to: :context
 
@@ -12,6 +13,7 @@ module PasskeysRails
       ensure_debug_mode
       ensure_regex_match
 
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e
@@ -20,18 +22,6 @@ module PasskeysRails
 
     private
 
-    def ensure_debug_mode
-      context.fail!(code: :not_allowed, message: 'Action not allowed') if username_regex.blank?
-    end
-
-    def ensure_regex_match
-      context.fail!(code: :not_allowed, message: 'Invalid username') unless username&.match?(username_regex)
-    end
-
-    def username_regex
-      PasskeysRails.debug_login_regex
-    end
-
     def agent
       @agent ||= begin
         agent = Agent.find_by(username:)

data/app/interactors/passkeys_rails/debug_register.rb

@@ -0,0 +1,44 @@
+# This functionality exists to allow easier mobile app debugging as it may not
+# be possible to acess Passkey functionality in mobile simulators.
+# It is only operational if DEBUG_LOGIN_REGEX is set in the server environment.
+# CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
+module PasskeysRails
+  class DebugRegister
+    include Interactor
+    include Debuggable
+    include AuthenticatableCreator
+
+    delegate :username, :authenticatable_info, to: :context
+
+    def call
+      ensure_debug_mode
+      ensure_regex_match
+
+      ActiveRecord::Base.transaction do
+        create_authenticatable! if aux_class_name.present?
+      end
+
+      context.agent = 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 agent
+      @agent ||= begin
+        result = BeginRegistration.call(username:)
+        context.fail!(code: result.code, message: result.message) if result.failure?
+
+        agent = Agent.find_by(username:)
+        context.fail!(code: :agent_not_found, message: "No agent found with that username") if agent.blank?
+
+        agent.update! registered_at: Time.current
+
+        agent
+      end
+    end
+  end
+end

data/app/interactors/passkeys_rails/finish_authentication.rb

@@ -8,6 +8,7 @@ module PasskeysRails
     def call
       verify_credential!
 
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e

data/app/interactors/passkeys_rails/finish_registration.rb

@@ -2,13 +2,19 @@
 module PasskeysRails
   class FinishRegistration
     include Interactor
+    include AuthenticatableCreator
 
     delegate :credential, :username, :challenge, :authenticatable_info, to: :context
 
     def call
       verify_credential!
-      store_passkey_and_register_agent!
 
+      agent.transaction do
+        store_passkey_and_register_agent!
+        create_authenticatable! if aux_class_name.present?
+      end
+
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e
@@ -26,66 +32,16 @@ module PasskeysRails
     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 aux_class_name.present?
-      end
-    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
-
-      @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
-
-        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)
+      # 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
 
     def webauthn_credential

data/app/interactors/passkeys_rails/refresh_token.rb

@@ -8,6 +8,7 @@ module PasskeysRails
     def call
       agent = ValidateAuthToken.call!(auth_token: token).agent
 
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e

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

@@ -7,6 +7,7 @@ module PasskeysRails
     included do
       has_one :agent, as: :authenticatable, class_name: "PasskeysRails::Agent"
 
+      delegate :username, to: :agent, allow_nil: true
       delegate :registered?, to: :agent, allow_nil: true
 
       def registering_with(_params)

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

@@ -0,0 +1,53 @@
+module PasskeysRails
+  module AuthenticatableCreator
+    extend ActiveSupport::Concern
+
+    protected
+
+    def create_authenticatable!
+      authenticatable = aux_class.new
+      authenticatable.agent = agent if authenticatable.respond_to?(:agent=)
+      authenticatable.registering_with(authenticatable_params) if authenticatable.respond_to?(:registering_with)
+      authenticatable.save!
+
+      agent.update!(authenticatable:)
+    rescue ActiveRecord::RecordInvalid => e
+      context.fail!(code: :record_invalid, message: e.message)
+    end
+
+    def aux_class_name
+      @aux_class_name ||= authenticatable_class || PasskeysRails.default_class
+    end
+
+    private
+
+    def authenticatable_class
+      authenticatable_info && authenticatable_info[:class]
+    end
+
+    def authenticatable_params
+      authenticatable_info && authenticatable_info[:params]
+    end
+
+    def aux_class
+      whitelist = PasskeysRails.class_whitelist
+
+      @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
+
+        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
+  end
+end

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

@@ -0,0 +1,19 @@
+module PasskeysRails
+  module Debuggable
+    extend ActiveSupport::Concern
+
+    protected
+
+    def ensure_debug_mode
+      context.fail!(code: :not_allowed, message: 'Action not allowed') if username_regex.blank?
+    end
+
+    def ensure_regex_match
+      context.fail!(code: :not_allowed, message: 'Invalid username') unless username&.match?(username_regex)
+    end
+
+    def username_regex
+      PasskeysRails.debug_login_regex
+    end
+  end
+end

data/config/routes.rb

@@ -1,13 +1,14 @@
 PasskeysRails::Engine.routes.draw do
-  post 'passkeys/challenge'
-  post 'passkeys/register'
-  post 'passkeys/authenticate'
-  post 'passkeys/refresh'
+  post 'challenge', to: 'passkeys#challenge'
+  post 'register', to: 'passkeys#register'
+  post 'authenticate', to: 'passkeys#authenticate'
+  post 'refresh', to: 'passkeys#refresh'
 
-  # This route exists to allow easier mobile app debugging as it may not
+  # These routes exist to allow easier mobile app debugging as it may not
   # be possible to acess Passkey functionality in mobile simulators.
   # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
   constraints(->(_request) { PasskeysRails.debug_login_regex.present? }) do
-    post 'passkeys/debug_login'
+    post 'debug_login', to: 'passkeys#debug_login'
+    post 'debug_register', to: 'passkeys#debug_register'
   end
 end

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

@@ -45,4 +45,19 @@ PasskeysRails.config do |c|
   # for example: %w[User AdminUser]
   #
   # c.class_whitelist = nil
+
+  # To subscribe to various events in PasskeysRails, use the subscribe method.
+  # It can be called multiple times to subscribe to more than one event.
+  #
+  # Valid events:
+  #   :did_register
+  #   :did_authenticate
+  #   :did_refresh
+  #
+  # Each event will include the event name, current agent and http request.
+  #
+  # For example:
+  # c.subscribe(:did_register) do |event, agent, request|
+  #   puts("#{event} | #{agent.id} | #{request.headers}")
+  # end
 end

data/lib/passkeys-rails.rb

@@ -45,6 +45,26 @@ module PasskeysRails
   # for example: %w[User AdminUser]
   mattr_accessor :class_whitelist, default: nil
 
+  # Convenience method to subscribe to various events in PasskeysRails.
+  #
+  # Valid events:
+  #   :did_register
+  #   :did_authenticate
+  #   :did_refresh
+  #
+  # Each event will include the event name, current agent and http request.
+  # For example:
+  #
+  # subscribe(:did_register) do |event, agent, request|
+  #   # do something with the agent and/or request
+  # end
+  #
+  def self.subscribe(event_name)
+    ActiveSupport::Notifications.subscribe("passkeys_rails.#{event_name}") do |name, _start, _finish, _id, payload|
+      yield(name.gsub(/^passkeys_rails\./, ''), payload[:agent], payload[:request]) if block_given?
+    end
+  end
+
   # This is only used by the debug_login endpoint.
   # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
   def self.debug_login_regex
@@ -53,6 +73,8 @@ module PasskeysRails
 
   # Returns an Interactor::Context that indicates if the request is authentic.
   #
+  # `request` can be a String on an Http Request
+  #
   # .success? is true if authentic
   # .agent is the Passkey::Agent on success
   #
@@ -60,10 +82,19 @@ module PasskeysRails
   # .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'])
+    auth_token = if request.is_a?(String)
+                   request
+                 elsif request.respond_to?(:headers)
+                   request.headers['X-Auth']
+                 else
+                   ""
+                 end
+
+    PasskeysRails::ValidateAuthToken.call(auth_token:)
   end
 
   # Raises a PasskeysRails::Error exception if the request is not authentic.
+  # `request` can be a String on an Http Request
   def self.authenticate!(request)
     auth = authenticate(request)
     return if auth.success?

data/lib/passkeys_rails/version.rb

@@ -1,3 +1,3 @@
 module PasskeysRails
-  VERSION = "0.2.0".freeze
+  VERSION = "0.3.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: passkeys-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Troy Anderson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-28 00:00:00.000000000 Z
+date: 2023-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -358,12 +358,15 @@ files:
 - app/interactors/passkeys_rails/begin_challenge.rb
 - app/interactors/passkeys_rails/begin_registration.rb
 - app/interactors/passkeys_rails/debug_login.rb
+- app/interactors/passkeys_rails/debug_register.rb
 - app/interactors/passkeys_rails/finish_authentication.rb
 - app/interactors/passkeys_rails/finish_registration.rb
 - app/interactors/passkeys_rails/generate_auth_token.rb
 - app/interactors/passkeys_rails/refresh_token.rb
 - app/interactors/passkeys_rails/validate_auth_token.rb
 - app/models/concerns/passkeys_rails/authenticatable.rb
+- app/models/concerns/passkeys_rails/authenticatable_creator.rb
+- app/models/concerns/passkeys_rails/debuggable.rb
 - app/models/passkeys_rails/agent.rb
 - app/models/passkeys_rails/application_record.rb
 - app/models/passkeys_rails/error.rb