Class: Decidim::AuthorizationHandler

Inherits:
Form show all
Defined in:
decidim-verifications/app/services/decidim/authorization_handler.rb

Overview

This is the base class for authorization handlers, all implementations should inherit from it. Each AuthorizationHandler is a form that will be used to check if the authorization is valid or not. When it is valid a new authorization will be created for the user.

Feel free to use validations to assert fields against a remote API, local database, or whatever.

It also sets two default attributes, ‘user` and `handler_name`.

Constant Summary

Constants included from Decidim::AttributeObject::TypeMap

Decidim::AttributeObject::TypeMap::Boolean, Decidim::AttributeObject::TypeMap::Decimal

Instance Attribute Summary

Attributes inherited from Decidim::AttributeObject::Form

#context

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Decidim::AttributeObject::Form

ensure_hash, from_model, from_params, hash_from, infer_model_name, #map_model, mimic, mimicked_model_name, model_name, #persisted?, #to_key, #to_model, #to_param, #valid?, #with_context

Methods included from Decidim::AttributeObject::Model

#[], #[]=, #attributes, #attributes_with_values, #initialize, #to_h

Class Method Details

.handler_for(name, params = {}) ⇒ Object

Finds a handler class from a String. This is necessary when processing the form data. It will only look for valid handlers that have also been configured in ‘Decidim.authorization_handlers`.

name - The String name of the class to find, usually in the same shape as the one returned by ‘handler_name`. params - An optional Hash with params to initialize the handler.

Returns an AuthorizationHandler descendant. Returns nil when no handlers could be found.



164
165
166
167
168
169
170
171
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 164

def self.handler_for(name, params = {})
  return unless name

  manifest = Decidim.authorization_handlers.find { |m| m.name == name }
  return unless manifest

  manifest.form.constantize.from_params(params || {})
end

.handler_name ⇒ Object

A serialized version of the handler’s name.

Returns a String.



143
144
145
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 143

def self.handler_name
  name.demodulize.underscore
end

Instance Method Details

#authorization_attributes ⇒ Object 



102
103
104
105
106
107
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 102

def authorization_attributes
  {
    unique_id:,
    metadata:
  }
end

#duplicate ⇒ Decidim::Authorization?

Fetches the duplicate record of the same authorization currently belonging to other user than the user being authorized.

Returns:

  • (Decidim::Authorization, nil) —

    The duplicate authorization record based on the unique ID or nil if there is no duplicate.



67
68
69
70
71
72
73
74
75
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 67

def duplicate
  return unless user

  Authorization.find_by(
    user: User.where.not(id: user.id).where(organization: user.organization),
    name: handler_name,
    unique_id:
  )
end

#ephemeral_tos_pending? ⇒ Boolean

Returns:



173
174
175
176
177
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 173

def ephemeral_tos_pending?
  return if user.blank?

  user.ephemeral? && !user.tos_accepted?
end

#form_attributes ⇒ Object

The attributes of the handler that should be exposed as form input when rendering the handler in a form.

Returns an Array of Strings.



81
82
83
84
85
86
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 81

def form_attributes
  excluded = %w(id user)
  excluded << "tos_agreement" unless ephemeral_tos_pending?

  attributes.except(*excluded).keys
end

#handler_name ⇒ Object

Same as the class method but accessible from the instance.

Returns a String.



150
151
152
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 150

def handler_name
  self.class.handler_name
end

#metadata ⇒ Object

Any data that the developer would like to inject to the ‘metadata` field of an authorization when it is created. Can be useful if some of the params the user sent with the authorization form want to be persisted for future use.

As a convention, an ‘extras’ key can be used to store information not directly related with authorization. Thus, when rendering previous verification data, on renewal, ‘extras’ is not rendered to the user.

Returns a Hash.



119
120
121
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 119

def metadata
  {}
end

#to_partial_path ⇒ Object

The String partial path so Rails can render the handler as a form. This is useful if you want to have a custom view to render the form instead of the default view.

Example:

A handler named Decidim::CensusHandler would look for its partial in:
decidim/census/form

Returns a String.



98
99
100
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 98

def to_partial_path
  "#{handler_name.sub!(/_handler$/, "")}/form"
end

#transferrable? ⇒ Boolean

Defines whether the duplicate authorizations can be transferred to a new user.

Returns:

  • (Boolean) —

    A boolean indicating whether the authorization can be transferred.



49
50
51
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 49

def transferrable?
  duplicate.present? && (duplicate.user.deleted? || duplicate.user.ephemeral?)
end

#unique? ⇒ Boolean

Defines whether the authorization is unique or if there is a duplicate for this particular authorization that matches the same unique_id.

Returns:

  • (Boolean) —

    A boolean indicating if the authorization has a duplicate.



40
41
42
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 40

def unique?
  unique_id.nil? || duplicate.blank?
end

#unique_id ⇒ Object

A unique ID to be implemented by the authorization handler that ensures no duplicates are created. This uniqueness check will be skipped if unique_id returns nil.



31
32
33
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 31

def unique_id
  nil
end

#user_transferrable? ⇒ Boolean

Defines whether the identity of an ephemeral user with the same authorization can be transferred to the current session and replace the existing user.

Returns:

  • (Boolean) —

    A boolean indicating whether the user identifier can be transferred.



58
59
60
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 58

def user_transferrable?
  duplicate.present? && [user, duplicate.user].all?(&:ephemeral?)
end

#verification_attachment ⇒ Object

An optional attachment to help out with verification.



136
137
138
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 136

def verification_attachment
  nil
end

#verification_metadata ⇒ Object

Any data to be injected in the ‘verification_metadata` field of an authorization when it is created. This data will be used for multi-step verification workflows in order to confirm the authorization.

Returns a Hash.



129
130
131
 
# File 'decidim-verifications/app/services/decidim/authorization_handler.rb', line 129

def verification_metadata
  {}
end