decidim-verifications 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0bcafbf13f475478c5f7f53c1c4c5493926dc09f
+  data.tar.gz: 86d57eecdd80590628847fcfe9d56139cc9114ad
+SHA512:
+  metadata.gz: 19c99dd7f94b58209f0c2f7bf0a31449c739c2f555992237f9226c2bdf17703c5b58a59c1982c40237b564483b37396cb587bbee453b64e0fb99e7bef5cfce4e
+  data.tar.gz: f799da0090c4168632ef49a25ef6c29abf2efe6c7101895c1f4320a5ebbe00a49a41fa387ac7361d98dac4782d455cd6f851fbb0a17edd791a629cba412f9a8d

data/README.md

@@ -0,0 +1,101 @@
+# Decidim::Verifications
+
+Decidim offers several methods for allowing participants to get authorization to
+perform certain privileged actions. This gem implements several of those methods
+and also offers a way for installation to implement their custom verification
+methods.
+
+## Introduction
+
+Each decidim instance is in full control of its authorizations, and can customize:
+
+* The different methods to be used by users to get verified. For example,
+  through a census, by uploading their identity documents, or by receiving a
+  verification home at their address.
+
+* The different actions in decidim that require authorization, and which
+  authorization method they require. For example, a decidim instance might
+  choose to require census authorization to create proposals, but a fully
+  verified address via a verification code sent by postal mail for voting on
+  proposals.
+
+## Types of authorization methods
+
+Decidim implements two type of authorization methods:
+
+* _Form authorizations_.
+
+  When your verification method is simple enough, you can use a `Rectify::Form`
+  to implement it. "Simple" here means that the authorization can be granted
+  with the submission of a single form. For example, to validate a user against
+  a census API you will need a form with some fields that your users will use to
+  authenticate against a census (for example, an ID and a Postal Code). You'll
+  implement this with a form class. See the documentation for the [parent
+  class][authorization handler base class] or have a look at a
+  [live example][live authorization handler example] in decidim-barcelona.
+
+  To register your handler, use
+
+  ```ruby
+  # config/initializers/decidim.rb
+
+  Decidim::Verifications.register_workflow(:census) do |workflow|
+    workflow.form = "<myAuthorizationHandlerClass"
+  end
+  ```
+
+* _Workflow authorizations_.
+
+  For more complex scenarios requiring several steps or admin intervention, you
+  can register a verification flow.
+
+  For example:
+
+  ```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
+  end
+  ```
+
+  Inside these engines, you can implement any steps required for the
+  authorization to succeed, via one or more custom controllers and views. You
+  can create partial `Authorization` records (with the `verified_at` column set
+  to `nil`) and hold partial verification data in the `verification_metadata`
+  column, or even a partial verification attachment in the
+  `verification_attachment` column.
+
+  Decidim currently requires that your main engine defines two routes:
+
+  * `new_authorization_path`: This is the entry point to start the authorization
+    process.
+
+  * `edit_authorization_path`: This is the entry point to resume an existing
+    authorization process.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'decidim-verifications'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+## Contributing
+
+See [Decidim](https://github.com/decidim/decidim).
+
+## License
+
+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
+[real authorization handler]: https://github.com/decidim/decidim-barcelona/blob/master/app/services/census_authorization_handler.rb

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "decidim/dev/common_rake"

data/app/commands/decidim/verifications/authorize_user.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    # A command to authorize a user with an authorization handler.
+    class AuthorizeUser < Rectify::Command
+      # Public: Initializes the command.
+      #
+      # handler - An AuthorizationHandler object.
+      def initialize(handler)
+        @handler = handler
+      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 handler.valid? && unique?
+
+        create_authorization
+        broadcast(:ok)
+      end
+
+      private
+
+      attr_reader :handler
+
+      def create_authorization
+        authorization = Authorization.find_or_initialize_by(
+          user: handler.user,
+          name: handler.handler_name
+        )
+
+        authorization.attributes = {
+          unique_id: handler.unique_id,
+          metadata: handler.metadata
+        }
+
+        authorization.grant!
+      end
+
+      def unique?
+        return true if handler.unique_id.nil?
+
+        duplicates = Authorization.where(
+          user: User.where.not(id: handler.user.id).where(organization: handler.user.organization.id),
+          name: handler.handler_name,
+          unique_id: handler.unique_id
+        )
+
+        return true unless duplicates.any?
+
+        handler.errors.add(:base, I18n.t("decidim.authorization_handlers.errors.duplicate_authorization"))
+        false
+      end
+    end
+  end
+end

data/app/commands/decidim/verifications/confirm_user_authorization.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    # A command to confirm a previous partial authorization.
+    class ConfirmUserAuthorization < Rectify::Command
+      # Public: Initializes the command.
+      #
+      # authorization - An Authorization to be confirmed.
+      # form - A form object with the verification data to confirm it.
+      def initialize(authorization, form)
+        @authorization = authorization
+        @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(:already_confirmed) if authorization.granted?
+
+        return broadcast(:invalid) unless form.valid?
+
+        if confirmation_successful?
+          authorization.grant!
+
+          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 :authorization, :form
+    end
+  end
+end

data/app/commands/decidim/verifications/perform_authorization_step.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    # A command to create a partial authorization for a user.
+    class PerformAuthorizationStep < Rectify::Command
+      # Public: Initializes the command.
+      #
+      # authorization - An Authorization object.
+      # handler - An AuthorizationHandler object.
+      def initialize(authorization, handler)
+        @authorization = authorization
+        @handler = handler
+      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 handler.valid?
+
+        update_verification_data
+
+        broadcast(:ok)
+      end
+
+      protected
+
+      def update_verification_data
+        authorization.attributes = {
+          unique_id: handler.unique_id,
+          metadata: handler.metadata,
+          verification_metadata: handler.verification_metadata,
+          verification_attachment: handler.verification_attachment
+        }
+
+        authorization.save!
+      end
+
+      private
+
+      attr_reader :authorization, :handler
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    # This controller allows users to create and destroy their authorizations. It
+    # shouldn't be necessary to expand it to add new authorization schemes.
+    class AuthorizationsController < Decidim::ApplicationController
+      helper_method :handler, :unauthorized_methods
+      before_action :valid_handler, only: [:new, :create]
+
+      include Decidim::UserProfile
+      helper Decidim::DecidimFormHelper
+      helper Decidim::CtaButtonHelper
+      helper Decidim::AuthorizationFormHelper
+
+      layout "layouts/decidim/user_profile", only: [:index]
+
+      def new; end
+
+      def index
+        @granted_authorizations = granted_authorizations
+        @pending_authorizations = pending_authorizations
+      end
+
+      def first_login
+        if unauthorized_methods.length == 1
+          redirect_to(
+            action: :new,
+            handler: unauthorized_methods.first.name,
+            redirect_url: decidim.account_path
+          )
+        end
+      end
+
+      def create
+        AuthorizeUser.call(handler) do
+          on(:ok) do
+            flash[:notice] = t("authorizations.create.success", scope: "decidim.verifications")
+            redirect_to params[:redirect_url] || authorizations_path
+          end
+
+          on(:invalid) do
+            flash[:alert] = t("authorizations.create.error", scope: "decidim.verifications")
+            render action: :new
+          end
+        end
+      end
+
+      protected
+
+      def handler
+        @handler ||= Decidim::AuthorizationHandler.handler_for(handler_name, handler_params)
+      end
+
+      def handler_params
+        (params[:authorization_handler] || {}).merge(user: current_user)
+      end
+
+      def handler_name
+        params[:handler] || params.dig(:authorization_handler, :handler_name)
+      end
+
+      def valid_handler
+        return true if handler
+
+        logger.warn "Invalid authorization handler given: #{handler_name} doesn't"\
+          "exist or you haven't added it to `Decidim.authorization_handlers`"
+
+        redirect_to(authorizations_path) && (return false)
+      end
+
+      def unauthorized_methods
+        @unauthorized_methods ||= available_verification_workflows.reject do |handler|
+          active_authorization_methods.include?(handler.key)
+        end
+      end
+
+      def active_authorization_methods
+        Authorizations.new(user: current_user).pluck(:name)
+      end
+
+      def granted_authorizations
+        Authorizations.new(user: current_user, granted: true)
+      end
+
+      def pending_authorizations
+        Authorizations.new(user: current_user, granted: false)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module IdDocuments
+      module Admin
+        #
+        # Handles confirmations for verification by identity document upload.
+        #
+        class ConfirmationsController < Decidim::Admin::ApplicationController
+          layout "decidim/admin/users"
+
+          before_action :load_pending_authorization
+
+          def new
+            authorize! :update, @pending_authorization
+
+            @form = InformationForm.new
+          end
+
+          def create
+            authorize! :update, @pending_authorization
+
+            @form = InformationForm.from_params(params)
+
+            ConfirmUserAuthorization.call(@pending_authorization, @form) do
+              on(:ok) do
+                flash[:notice] = t("confirmations.create.success", scope: "decidim.verifications.id_documents.admin")
+                redirect_to pending_authorizations_path
+              end
+
+              on(:invalid) do
+                flash.now[:alert] = t("confirmations.create.error", scope: "decidim.verifications.id_documents.admin")
+                render action: :new
+              end
+            end
+          end
+
+          private
+
+          def load_pending_authorization
+            @pending_authorization = Authorization.find(params[:pending_authorization_id])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Verifications
+    module IdDocuments
+      module Admin
+        class PendingAuthorizationsController < Decidim::Admin::ApplicationController
+          layout "decidim/admin/users"
+
+          def index
+            authorize! :index, Authorization
+
+            @pending_authorizations = pending_authorizations
+          end
+
+          private
+
+          def pending_authorizations
+            Authorizations
+              .new(name: "id_documents", granted: false)
+              .query
+              .where("verification_metadata->'rejected' IS NULL")
+          end
+        end
+      end
+    end
+  end
+end