decidim-verifications 0.15.2 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35989fb875c3a9a35ef5b25cb46952b655cb2f506ec1cf6ad32560e7aba51523
-  data.tar.gz: 0d797f5a1c10a56816f206b42d737effd16919372f4a9addcd09026c0e79bdeb
+  metadata.gz: 3f72535ac2342a5548bc109d27133bdbbc04ea5d31bf75e6bea9388129cfd962
+  data.tar.gz: 65a300dbe94c86dc4a185946617608e78cf912879df40aca37b72e4eb08504a8
 SHA512:
-  metadata.gz: 97d9d80cf83c94b581158614ca5490f8aced492cb054bebad163eda1e6c2f67486a4c3f55330ab9b69eca2ebdb21b20e9304ae6fff0e7c10b8578b2f1c3d5724
-  data.tar.gz: 35cf389ed2c0376d767d52c5587575806e17e465c88ee8af9f62691e27c5633e9c8ae135874ac2981667315721b37177d5f176681c1827c71d2bac9a34453fb0
+  metadata.gz: d8aea64e88a8f1ec983ee81e4ccdaab8c6788077ef171aac9ba432710eddbbf2d595e9a8200c0b5cff2735fc1b3659d4d4384c77d8c73cb6a369c33f4d0be550
+  data.tar.gz: 27e690f78d70610141648ec4acc0551401aa904476caeb842de371a57586cdd812ea2c5ab3dc23c27328a6f220deb5a4210b4b515305ce860c890304cfd57af0

data/README.md

@@ -76,9 +76,9 @@ Decidim implements two type of authorization methods:
   ```ruby
   # config/initializers/decidim.rb
 
-  Decidim::Verifications.register_workflow(:sms_verification) do |workflow|
-    workflow.engine = Decidim::Verifications::SmsVerification::Engine
-    workflow.admin_engine = Decidim::Verifications::SmsVerification::AdminEngine
+  Decidim::Verifications.register_workflow(:my_verification) do |workflow|
+    workflow.engine = Decidim::Verifications::MyVerification::Engine
+    workflow.admin_engine = Decidim::Verifications::MyVerification::AdminEngine
   end
   ```
 
@@ -97,6 +97,24 @@ Decidim implements two type of authorization methods:
   * `edit_authorization_path`: This is the entry point to resume an existing
     authorization process.
 
+### SMS verification
+
+Decidim comes with a verification workflow designed to verify users by sending
+an SMS to their mobile phone.
+
+Much like a Census verification you just need to implement a class that sends an
+SMS code using your preferred provider.
+
+In order to setup Decidim with SMS verification you need to:
+
+1. Create a class that accepts two parameters when initializing it (mobile phone and code) and a method named `deliver_code` that will send an SMS and return a truthy or falsey value if the delivery was OK or not.
+1. Set the `sms_gateway_service` configuration variable to the name of the class that you just created (use a String, not the actual class) at `config/initializers/decidim.rb`.
+
+Keep in mind that Decidim won't store a free text version of the mobile phone, only a hashed
+version so we can avoid duplicates and guarantee the users' privacy.
+
+You can find an example [here][example SMS gateway].
+
 ## Authorization options
 
 Sometimes you want to scope authorizations only to users that meet certain
@@ -163,10 +181,10 @@ its workflow manifest:
 ```ruby
 # config/initializers/decidim.rb
 
-Decidim::Verifications.register_workflow(:sms_verification) do |workflow|
-  workflow.engine = Decidim::Verifications::SmsVerification::Engine
-  workflow.admin_engine = Decidim::Verifications::SmsVerification::AdminEngine
-  workflow.action_authorizer = "Decidim::Verifications::SmsVerification::ActionAuthorizer"
+Decidim::Verifications.register_workflow(:my_verification) do |workflow|
+  workflow.engine = Decidim::Verifications::MyVerification::Engine
+  workflow.admin_engine = Decidim::Verifications::MyVerification::AdminEngine
+  workflow.action_authorizer = "Decidim::Verifications::MyVerification::ActionAuthorizer"
 end
 ```
 
@@ -174,6 +192,17 @@ Check the [example authorization handler](https://github.com/decidim/decidim/blo
 and the [DefaultActionAuthorizer class](https://github.com/decidim/decidim/blob/master/decidim-verifications/lib/decidim/verifications/default_action_authorizer.rb)
 for additional technical details.
 
+## How Handlers work
+
+For a workflow to be visible in the user's profile, the organization must have
+it in it's `available_authorizations` and the given handler must exist.
+The name of the handler must match the authorization name plus the "Hander"
+suffix. It also has to be in the `Decidim::Verifications` namespace.
+
+The handler is both the Form object that the user must fill in order to be
+verified, but also the validator of the filled information in order to grant the
+authorization.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -197,6 +226,7 @@ See [Decidim](https://github.com/decidim/decidim).
 See [Decidim](https://github.com/decidim/decidim).
 
 [authorization handler base class]: https://github.com/decidim/decidim/blob/master/decidim-core/app/services/decidim/authorization_handler.rb
+[example SMS gateway]: https://github.com/decidim/decidim/blob/master/decidim-verifications/lib/decidim/verifications/sms/example_gateway.rb
 
 [Decidim Barcelona]: https://github.com/AjuntamentdeBarcelona/decidim-barcelona/blob/master/app/services/census_authorization_handler.rb
 [Decidim Terrassa]: https://github.com/AjuntamentDeTerrassa/decidim-terrassa/blob/master/app/services/census_authorization_handler.rb

data/app/commands/decidim/verifications/id_documents/admin/confirm_user_offline_authorization.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module IdDocuments
+      module Admin
+        # A command to confirm a previous partial offline authorization.
+        class ConfirmUserOfflineAuthorization < Rectify::Command
+          # Public: Initializes the command.
+          #
+          # form - A form object with the verification data to confirm it.
+          def initialize(form)
+            @form = form
+          end
+
+          # Executes the command. Broadcasts these events:
+          #
+          # - :ok when everything is valid.
+          # - :invalid if the handler wasn't valid and we couldn't proceed.
+          #
+          # Returns nothing.
+          def call
+            return broadcast(:invalid) unless form.valid?
+            return broadcast(:invalid) unless authorization
+
+            if confirmation_successful?
+              grant_authorization
+              broadcast(:ok)
+            else
+              broadcast(:invalid)
+            end
+          end
+
+          protected
+
+          def confirmation_successful?
+            form.verification_metadata.all? do |key, value|
+              authorization.verification_metadata[key] == value
+            end
+          end
+
+          private
+
+          attr_reader :form
+
+          def grant_authorization
+            Decidim.traceability.perform_action!(
+              :grant_id_documents_offline_verification,
+              authorization_user,
+              form.current_user
+            ) do
+              authorization.grant!
+            end
+          end
+
+          def authorization
+            @authorization ||= Authorizations
+                               .new(organization: form.current_organization, name: "id_documents", granted: false)
+                               .query
+                               .where("verification_metadata->'rejected' IS NULL")
+                               .where("verification_metadata->>'verification_type' = 'offline'")
+                               .find_by(user: authorization_user)
+          end
+
+          def authorization_user
+            @authorization_user ||= Decidim::User
+                                    .where(organization: form.current_organization)
+                                    .find_by(email: form.email)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/verifications/id_documents/admin/update_config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module IdDocuments
+      module Admin
+        class UpdateConfig < Rectify::Command
+          def initialize(form)
+            @form = form
+          end
+
+          def call
+            return broadcast(:invalid) if form.invalid?
+
+            update_config
+
+            broadcast(:ok)
+          end
+
+          private
+
+          attr_reader :form
+
+          def update_config
+            Decidim.traceability.perform_action!(
+              :update_id_documents_config,
+              form.current_organization,
+              form.current_user
+            ) do
+              form.current_organization.id_documents_methods = form.selected_methods
+              form.current_organization.id_documents_explanation_text = form.offline_explanation
+              form.current_organization.save!
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/verifications/id_documents/admin/config_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module IdDocuments
+      module Admin
+        #
+        # Handles the configuration for the ID documents verification
+        #
+        class ConfigController < Decidim::Admin::ApplicationController
+          layout "decidim/admin/users"
+
+          def edit
+            enforce_permission_to :update, :organization, organization: current_organization
+
+            @form = form(ConfigForm).from_model(current_organization)
+          end
+
+          def update
+            enforce_permission_to :update, :organization, organization: current_organization
+
+            @form = form(ConfigForm).from_params(params)
+
+            UpdateConfig.call(@form) do
+              on(:ok) do
+                flash[:notice] = t("config.update.success", scope: "decidim.verifications.id_documents.admin")
+                redirect_to pending_authorizations_path
+              end
+
+              on(:invalid) do
+                flash.now[:alert] = t("config.update.error", scope: "decidim.verifications.id_documents.admin")
+                render action: :edit
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/verifications/id_documents/admin/offline_confirmations_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module IdDocuments
+      module Admin
+        #
+        # Handles confirmations for offline verification by identity document.
+        #
+        class OfflineConfirmationsController < Decidim::Admin::ApplicationController
+          layout "decidim/admin/users"
+
+          def new
+            enforce_permission_to :update, :authorization
+
+            @form = form(OfflineConfirmationForm).instance
+          end
+
+          def create
+            enforce_permission_to :update, :authorization
+
+            @form = form(OfflineConfirmationForm).from_params(params)
+
+            ConfirmUserOfflineAuthorization.call(@form) do
+              on(:ok) do
+                flash[:notice] = t("offline_confirmations.create.success", scope: "decidim.verifications.id_documents.admin")
+                redirect_to pending_authorizations_path
+              end
+
+              on(:invalid) do
+                flash.now[:alert] = t("offline_confirmations.create.error", scope: "decidim.verifications.id_documents.admin")
+                render action: :new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/verifications/id_documents/admin/pending_authorizations_controller.rb

@@ -7,19 +7,30 @@ module Decidim
         class PendingAuthorizationsController < Decidim::Admin::ApplicationController
           layout "decidim/admin/users"
 
+          helper_method :has_offline_method?
+
           def index
             enforce_permission_to :index, :authorization
 
-            @pending_authorizations = pending_authorizations
+            @pending_online_authorizations = pending_online_authorizations
           end
 
           private
 
-          def pending_authorizations
+          def pending_online_authorizations
             Authorizations
               .new(organization: current_organization, name: "id_documents", granted: false)
               .query
               .where("verification_metadata->'rejected' IS NULL")
+              .where("verification_metadata->>'verification_type' = 'online'")
+          end
+
+          def has_offline_method?
+            available_methods.include?("offline")
+          end
+
+          def available_methods
+            @available_methods ||= current_organization.id_documents_methods
           end
         end
       end

data/app/controllers/decidim/verifications/id_documents/authorizations_controller.rb

@@ -7,14 +7,20 @@ module Decidim
       # Handles verification by identity document upload
       #
       class AuthorizationsController < ApplicationController
-        helper_method :authorization
+        helper_method :authorization, :verification_type, :using_offline?, :using_online?, :available_methods
 
         before_action :load_authorization
 
+        def choose
+          return redirect_to action: :new, using: verification_type if available_methods.count == 1
+          render :choose
+        end
+
         def new
+          raise ActionController::RoutingError, "Method not available" unless available_methods.include?(verification_type)
           enforce_permission_to :create, :authorization, authorization: @authorization
 
-          @form = UploadForm.new
+          @form = UploadForm.from_params(id_document_upload: { verification_type: verification_type })
         end
 
         def create
@@ -47,6 +53,7 @@ module Decidim
           @form = UploadForm.from_params(
             params.merge(
               user: current_user,
+              verification_type: verification_type,
               verification_attachment: params[:id_document_upload][:verification_attachment] || @authorization.verification_attachment
             )
           )
@@ -78,6 +85,27 @@ module Decidim
             name: "id_documents"
           )
         end
+
+        def verification_type
+          params[:using] || authorization_verification_type || available_methods.first
+        end
+
+        def authorization_verification_type
+          return unless @authorization
+          @authorization.verification_metadata["verification_type"]
+        end
+
+        def using_online?
+          verification_type == "online"
+        end
+
+        def using_offline?
+          verification_type == "offline"
+        end
+
+        def available_methods
+          @available_methods ||= current_organization.id_documents_methods
+        end
       end
     end
   end

data/app/controllers/decidim/verifications/sms/authorizations_controller.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module Sms
+      class AuthorizationsController < ApplicationController
+        helper_method :authorization
+
+        before_action :load_authorization
+
+        def new
+          enforce_permission_to :create, :authorization, authorization: @authorization
+
+          @form = MobilePhoneForm.new
+        end
+
+        def create
+          enforce_permission_to :create, :authorization, authorization: @authorization
+
+          @form = MobilePhoneForm.from_params(params.merge(user: current_user))
+
+          PerformAuthorizationStep.call(@authorization, @form) do
+            on(:ok) do
+              flash[:notice] = t("authorizations.create.success", scope: "decidim.verifications.sms")
+              authorization_method = Decidim::Verifications::Adapter.from_element(authorization.name)
+              redirect_to authorization_method.resume_authorization_path
+            end
+            on(:invalid) do
+              flash.now[:alert] = t("authorizations.create.error", scope: "decidim.verifications.sms")
+              render :new
+            end
+          end
+        end
+
+        def edit
+          enforce_permission_to :update, :authorization, authorization: @authorization
+
+          @form = ConfirmationForm.from_params(params)
+        end
+
+        def update
+          enforce_permission_to :update, :authorization, authorization: @authorization
+
+          @form = ConfirmationForm.from_params(params)
+
+          ConfirmUserAuthorization.call(@authorization, @form) do
+            on(:ok) do
+              flash[:notice] = t("authorizations.update.success", scope: "decidim.verifications.sms")
+              redirect_to decidim_verifications.authorizations_path
+            end
+
+            on(:invalid) do
+              flash.now[:alert] = t("authorizations.update.error", scope: "decidim.verifications.sms")
+              render :edit
+            end
+          end
+        end
+
+        private
+
+        # rubocop:disable Naming/MemoizedInstanceVariableName
+        def authorization
+          @authorization_presenter ||= AuthorizationPresenter.new(@authorization)
+        end
+        # rubocop:enable Naming/MemoizedInstanceVariableName
+
+        def load_authorization
+          @authorization = Decidim::Authorization.find_or_initialize_by(
+            user: current_user,
+            name: "sms"
+          )
+        end
+      end
+    end
+  end
+end