devise_invitable 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52005f95e25dca6edd01fb9193500a319035974cdf3cd643133ae7c2f42e7825
-  data.tar.gz: 25b2fa545162bb87340c1133811bacf61861fc2eb914b002618531815f576fe7
+  metadata.gz: 96e5afbd2a5df8b9d94f1b1cbe30a2544f6c759b9c5c4ccb4f1de2a37a8f6e3a
+  data.tar.gz: ccef0234148611c07c9eae801b104da63066fd856ea3d1bd592180936e1a3042
 SHA512:
-  metadata.gz: 6f512c5c9be3eb3a5b80abc6adec76b5dd5432f4ed02e3596f9ab9c9bc297589b452556c0a828f0a64db91bd7152ad8b31f43b91a82b013e7bce32e1fd76bf13
-  data.tar.gz: 10d177422be705e605c9287785cc0d6ec42d5b42ae40ee646d7bb8f6c08521612217fb3735ae790975bfc7da7b7f6b459eb0beeb2d3c06e9648d340f9538526a
+  metadata.gz: e81ee3d1513dded1dbaaf4685bea5fe71c6d4f08bc57bec248407488ce9f0122498a3dac8c9e80a0db7cf8812bc36c88b570d4688cad52360076d439e172a8ae
+  data.tar.gz: db4f74177f9f44b361f689a3ebb58e49e42827e07ee39f98dfb9c907a0d1e4e2704381d24e101d41014fc8a1125eb9dbdd01131e694b572580669bb7c8ae2b9d

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## Unreleased
+
+## 3.0.1
+
+- Raise `DeviseInvitable::AmbiguousInviteKeyError` instead of selecting an
+  arbitrary resource when an invite key matches multiple records
+  ([#878](https://github.com/scambra/devise_invitable/issues/878))
+- Use the signed-in resource as the inviter when a custom
+  `authenticate_inviter!` method returns a boolean success value
+  ([#825](https://github.com/scambra/devise_invitable/issues/825))
+- Do not assign attributes or modify associations on an existing resource when
+  its invitation is rejected ([#747](https://github.com/scambra/devise_invitable/issues/747))
+- Avoid uninitialized `@accepting_invitation` warnings on supported Ruby 2.7
+  ([#776](https://github.com/scambra/devise_invitable/issues/776))
+- Document personal-data storage and retention considerations for deferred and
+  placeholder invitations ([#777](https://github.com/scambra/devise_invitable/issues/777))
+- Add regression coverage for custom `authenticate_inviter!` methods that
+  redirect unauthorized inviters ([#893](https://github.com/scambra/devise_invitable/issues/893))
+- Add regression coverage to ensure `devise_for` preserves a custom controller
+  `module` instead of replacing its registrations controller
+  ([#877](https://github.com/scambra/devise_invitable/issues/877))
+- Add regression coverage that instance-level `invite!` runs both the before
+  and after invitation-created callbacks
+  ([#640](https://github.com/scambra/devise_invitable/issues/640))
+
 ## 3.0.0
 
 - Drop support for Ruby < 2.7, Rails < 7.0, and Devise < 5.0

data/README.md

@@ -246,6 +246,34 @@ above is `'users/invitations'`, so our routes.rb would have this line:
 devise_for :users, controllers: { invitations: 'users/invitations' }
 ```
 
+The invitations controller prepends its authentication, invitation-limit, and
+token-loading callbacks. These callbacks may render or redirect and halt the
+callback chain before an ordinary callback inherited from
+`ApplicationController` runs. If application context must be available even
+when one of these guards halts the request, prepend that setup in the custom
+invitations controller. For example, an around callback can set and restore
+the locale so flash messages created by the guards use the requested locale:
+
+```ruby
+class Users::InvitationsController < Devise::InvitationsController
+  prepend_around_action :use_locale
+
+  private
+
+    def use_locale(&action)
+      I18n.with_locale(locale_from_request, &action)
+    end
+
+    def locale_from_request
+      params[:locale].presence_in(I18n.available_locales.map(&:to_s)) ||
+        I18n.default_locale
+    end
+end
+```
+
+The same ordering rule applies to tenant selection, request tracing, and other
+setup that must run before Devise Invitable's controller guards.
+
 be sure that you generate the views and put them into the controller that you
 generated, so for this example it would be:
 
@@ -394,6 +422,36 @@ rejected by both Devise's password validation and
 `active_for_authentication?` checks until an invitation is accepted or the
 resource is claimed by direct registration.
 
+### Privacy and data retention
+
+Invitation keys commonly contain personal data such as an email address. With
+the default `create_resource_on_invitation: false`, no resource row is created,
+but the invite-key values are stored in plaintext in the
+`devise_invitations.invite_key` JSON column so the resource can be created when
+the invitation is accepted. `invite_key_digest` is used for matching; it does
+not replace the stored values and should not be treated as anonymization.
+
+With `create_resource_on_invitation: true`, the resource and any additional
+attributes or associations supplied to `invite!` are persisted immediately.
+Choose this mode only when the application needs a placeholder and its privacy
+policy permits storing that data before acceptance.
+
+`invite_for` limits token validity but does not delete invitation or resource
+records. Applications are responsible for choosing a lawful basis for
+processing, disclosing that processing where required, limiting invited data,
+restricting access, protecting it at rest, and deleting pending, revoked,
+superseded, and accepted invitation data according to their retention policy.
+Consent is one possible lawful basis under GDPR, but it is not the only one.
+See the [European Commission GDPR principles](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/principles-gdpr_en)
+and obtain appropriate legal advice for the application.
+
+A one-way hash alone is insufficient for the built-in deferred-invitation
+flow, because devise_invitable must recover the invite keys to create the
+resource at acceptance. Applications that must not retain the email address
+need a custom flow, such as asking the invitee to enter it during acceptance
+and verifying it against a stored digest, or using suitably protected
+reversible storage.
+
 If you want to create the invitation but not send it, you can set
 `skip_invitation` to `true`.
 

data/app/controllers/devise/invitations_controller.rb

@@ -85,7 +85,13 @@ class Devise::InvitationsController < DeviseController
     end
 
     def current_inviter
-      authenticate_inviter!
+      authenticated = authenticate_inviter!
+      return authenticated if authenticated.respond_to?(:has_invitations_left?)
+
+      # Custom API/token authenticators may return true on success instead of
+      # the authenticated resource, so fall back to Devise's current scope.
+      current_resource_method = :"current_#{resource_name}"
+      send(current_resource_method) if respond_to?(current_resource_method, true)
     end
 
     def has_invitations_left?

data/lib/devise_invitable/models.rb

@@ -231,7 +231,7 @@ module Devise
 
       # Returns true if accept_invitation! was called
       def accepting_invitation?
-        @accepting_invitation
+        instance_variable_defined?(:@accepting_invitation) && @accepting_invitation
       end
 
       # Verifies whether a user accepted an invitation (false when user is accepting it)
@@ -494,8 +494,18 @@ module Devise
             attributes_hash[k] = attribute
           end
 
+          ensure_unique_invite_key_match!(invite_key_array, attributes_hash)
           invitable = find_or_initialize_with_errors(invite_key_array, attributes_hash)
           invitable.assign_attributes(attributes_hash)
+          # Association writers may persist changes immediately. Reject an
+          # existing resource before assigning non-key attributes or yielding.
+          if invitable.persisted? && (invitable.invitation_taken? || !self.resend_invitation)
+            invite_key_array.each do |key|
+              invitable.add_taken_error(key)
+            end
+            return [invitable, nil]
+          end
+
           invitable.assign_attributes(attributes)
           invitable.skip_invitation = skip_invitation unless skip_invitation.nil?
           invitable.invited_by_for_next_invitation = invited_by
@@ -508,10 +518,6 @@ module Devise
             invite_key_array.each { |key| invitable.add_taken_error(key) }
           elsif invitable.new_record?
             invitable.clear_errors_on_valid_keys if !self.validate_on_invite
-          elsif invitable.invitation_taken? || !self.resend_invitation
-            invite_key_array.each do |key|
-              invitable.add_taken_error(key)
-            end
           end
 
           resource_attribute_names = attributes.keys.map(&:to_sym)
@@ -639,6 +645,20 @@ module Devise
 
         private
 
+          def ensure_unique_invite_key_match!(required_attributes, attributes)
+            filtered_attributes = attributes.to_h.with_indifferent_access
+              .slice(*required_attributes)
+              .delete_if { |_key, value| value.blank? }
+            return unless filtered_attributes.size == required_attributes.size
+
+            filtered_attributes = devise_parameter_filter.filter(filtered_attributes)
+            matches = where(filtered_attributes).limit(2).to_a
+            return unless matches.many?
+
+            raise DeviseInvitable::AmbiguousInviteKeyError,
+              "Invite key matches multiple #{devise_invitable_base_class.name} records"
+          end
+
           # The random password, as set after an invitation, must conform
           # to any password format validation rules of the application.
           # This default fixes the most common scenarios: Passwords must contain

data/lib/devise_invitable/version.rb

@@ -1,3 +1,3 @@
 module DeviseInvitable
-  VERSION = '3.0.0'.freeze
+  VERSION = '3.0.1'.freeze
 end

data/lib/devise_invitable.rb

@@ -1,4 +1,5 @@
 module DeviseInvitable
+  class AmbiguousInviteKeyError < StandardError; end
   class ResourceAttributesRequirePlaceholderError < ArgumentError; end
 
   autoload :Inviter, 'devise_invitable/inviter'

data/test/integration/invitation_test.rb

@@ -247,6 +247,27 @@ class InvitationTest < ActionDispatch::IntegrationTest
     assert_redirected_to new_admin_session_path
   end
 
+  test 'custom inviter authentication can redirect without rendering twice' do
+    sign_in_as_user
+
+    get new_restricted_invitation_path
+
+    assert_redirected_to root_path
+    assert_equal 'You are not authorized to access this page', flash[:alert]
+  end
+
+  test 'boolean inviter authentication uses the signed in resource as inviter' do
+    inviter = User.create!(
+      email: 'boolean-inviter@example.com',
+      password: '123456',
+      password_confirmation: '123456'
+    )
+
+    post boolean_inviter_invitation_path, params: { user: { email: 'boolean-invitee@example.com' } }
+
+    assert_equal inviter, User.find_by!(email: 'boolean-invitee@example.com').invited_by
+  end
+
   test 'authenticated admin should be able to send an admin invitation' do
     admin = Admin.create(email: 'admin@test.com', password: '123456', password_confirmation: '123456')
     sign_in_as_user admin

data/test/models/invitable_test.rb

@@ -15,6 +15,17 @@ class InvitableTest < ActiveSupport::TestCase
     assert_nil new_user.invitation_token
   end
 
+  test 'accepting_invitation? does not warn before invitation acceptance' do
+    original_verbose = $VERBOSE
+    $VERBOSE = true
+
+    _, warnings = capture_io { refute_predicate new_user, :accepting_invitation? }
+
+    refute_includes warnings, 'instance variable @accepting_invitation not initialized'
+  ensure
+    $VERBOSE = original_verbose
+  end
+
   test 'should update the invitations count counter cache' do
     if defined?(ActiveRecord)
       current_user = new_user
@@ -430,6 +441,30 @@ class InvitableTest < ActiveSupport::TestCase
     assert_equal [{error: :taken}], same_user.errors.details[:email]
   end
 
+  test 'should not modify associations when an existing user cannot be invited' do
+    existing_user = User.create!(email: 'existing@email.com', password: '123456789')
+    User.invite!({ email: 'invitee@email.com' }, existing_user)
+    sent_invitation = existing_user.sent_invitations.first
+
+    invited_user = User.invite!(
+      email: existing_user.email,
+      sent_invitation_ids: []
+    )
+
+    assert_equal [{ error: :taken }], invited_user.errors.details[:email]
+    assert_equal existing_user, sent_invitation.reload.invited_by
+  end
+
+  test 'should reject an invite key that matches multiple records' do
+    2.times do
+      User.new(email: 'duplicate@email.com').save(validate: false)
+    end
+
+    assert_raises DeviseInvitable::AmbiguousInviteKeyError do
+      User.invite!(email: 'duplicate@email.com')
+    end
+  end
+
   test 'should return a record with errors if user with pending invitation was found by e-mail' do
     existing_user = User.invite!(email: 'valid@email.com')
     user = User.invite!(email: 'valid@email.com')
@@ -447,7 +482,7 @@ class InvitableTest < ActiveSupport::TestCase
     end
   end
 
-  test 'should return a record with errors if user was found by e-mail with validate_on_invite' do
+  test 'should not assign or validate other attributes if user was found by e-mail' do
     begin
       validate_on_invite = User.validate_on_invite
       User.validate_on_invite = true
@@ -456,7 +491,8 @@ class InvitableTest < ActiveSupport::TestCase
       user = User.invite!(email: 'valid@email.com', username: 'a' * 50)
       assert_equal user, existing_user
       assert_equal [{error: :taken}], user.errors.details[:email]
-      refute_empty user.errors[:username]
+      assert_empty user.errors[:username]
+      assert_nil user.username
     ensure
       User.validate_on_invite = validate_on_invite
     end
@@ -741,8 +777,10 @@ class InvitableTest < ActiveSupport::TestCase
 
   test "user.invite! should trigger callbacks" do
     user = User.new(email: 'valid@email.com')
+    assert_callbacks_not_fired :before_invitation_created, user
     assert_callbacks_not_fired :after_invitation_created, user
     user.invite!
+    assert_callbacks_fired :before_invitation_created, user
     assert_callbacks_fired :after_invitation_created, user
   end
 

data/test/rails_app/app/controllers/boolean_inviter_invitations_controller.rb

@@ -0,0 +1,11 @@
+class BooleanInviterInvitationsController < Devise::InvitationsController
+  protected
+
+    def authenticate_inviter!
+      true
+    end
+
+    def current_user
+      User.find_by(email: 'boolean-inviter@example.com')
+    end
+end

data/test/rails_app/app/controllers/restricted_invitations_controller.rb

@@ -0,0 +1,9 @@
+class RestrictedInvitationsController < Devise::InvitationsController
+  protected
+
+    def authenticate_inviter!
+      return if current_admin
+
+      redirect_back fallback_location: root_path, alert: 'You are not authorized to access this page'
+    end
+end

data/test/rails_app/app/models/user.rb

@@ -37,7 +37,8 @@ class User < PARENT_MODEL_CLASS
   devise :database_authenticatable, :registerable, :validatable, :confirmable, :invitable, :recoverable,
     create_resource_on_invitation: true
 
-  attr_accessor :after_invitation_created_callback_works, :after_invitation_accepted_callback_works, :bio, :token
+  attr_accessor :before_invitation_created_callback_works, :after_invitation_created_callback_works,
+    :after_invitation_accepted_callback_works, :bio, :token
   validates :username, length: { maximum: 20 }
 
   attr_accessor :testing_accepted_or_not_invited
@@ -53,6 +54,10 @@ class User < PARENT_MODEL_CLASS
     object.after_invitation_created_callback_works = true
   end
 
+  before_invitation_created do |object|
+    object.before_invitation_created_callback_works = true
+  end
+
   after_invitation_accepted do |object|
     object.after_invitation_accepted_callback_works = true
   end

data/test/rails_app/config/routes.rb

@@ -1,7 +1,9 @@
 RailsApp::Application.routes.draw do
   devise_for :users
   devise_scope :user do
+    resource :boolean_inviter_invitation, only: [:new, :create]
     resource :free_invitation, only: [:new, :create]
+    resource :restricted_invitation, only: [:new, :create]
     resource :admin, only: [:new, :create]
   end
   devise_for :admins

data/test/routes_test.rb

@@ -2,6 +2,12 @@ require 'test_helper'
 
 class RoutesTest < ActionController::TestCase
 
+  test 'preserve custom controller module for registrations' do
+    mapping = Devise::Mapping.new(:users, module: :users)
+
+    assert_equal 'users/registrations', mapping.controllers[:registrations]
+  end
+
   test 'map new user invitation' do
     assert_recognizes({ controller: 'devise/invitations', action: 'new' }, { path: 'users/invitation/new', method: :get })
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: devise_invitable
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Sergio Cambra
@@ -137,8 +137,10 @@ files:
 - test/rails_app/Rakefile
 - test/rails_app/app/controllers/admins_controller.rb
 - test/rails_app/app/controllers/application_controller.rb
+- test/rails_app/app/controllers/boolean_inviter_invitations_controller.rb
 - test/rails_app/app/controllers/free_invitations_controller.rb
 - test/rails_app/app/controllers/home_controller.rb
+- test/rails_app/app/controllers/restricted_invitations_controller.rb
 - test/rails_app/app/controllers/users_controller.rb
 - test/rails_app/app/helpers/application_helper.rb
 - test/rails_app/app/mailers/application_mailer.rb
@@ -219,8 +221,10 @@ test_files:
 - test/rails_app/Rakefile
 - test/rails_app/app/controllers/admins_controller.rb
 - test/rails_app/app/controllers/application_controller.rb
+- test/rails_app/app/controllers/boolean_inviter_invitations_controller.rb
 - test/rails_app/app/controllers/free_invitations_controller.rb
 - test/rails_app/app/controllers/home_controller.rb
+- test/rails_app/app/controllers/restricted_invitations_controller.rb
 - test/rails_app/app/controllers/users_controller.rb
 - test/rails_app/app/helpers/application_helper.rb
 - test/rails_app/app/mailers/application_mailer.rb