smart-id-ruby-client 0.1.0

data/lib/smart_id_ruby/device_link_interaction.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  # Represents interaction payload used in device-link-based flows.
+  class DeviceLinkInteraction
+    DISPLAY_TEXT_AND_PIN = "displayTextAndPIN"
+    CONFIRMATION_MESSAGE = "confirmationMessage"
+
+    DISPLAY_TEXT_60_MAX_LENGTH = 60
+    DISPLAY_TEXT_200_MAX_LENGTH = 200
+
+    attr_reader :type, :display_text60, :display_text200
+
+    def initialize(type:, display_text60: nil, display_text200: nil)
+      @type = type&.to_s
+      @display_text60 = display_text60
+      @display_text200 = display_text200
+
+      validate!
+    end
+
+    def to_h
+      {
+        type: type,
+        displayText60: display_text60,
+        displayText200: display_text200
+      }.compact
+    end
+
+    def self.display_text_and_pin(display_text60)
+      new(type: DISPLAY_TEXT_AND_PIN, display_text60: display_text60)
+    end
+
+    def self.confirmation_message(display_text200)
+      new(type: CONFIRMATION_MESSAGE, display_text200: display_text200)
+    end
+
+    private
+
+    def validate!
+      raise SmartIdRuby::Errors::RequestSetupError, "Value for 'type' must be set" if blank?(type)
+
+      case type
+      when DISPLAY_TEXT_AND_PIN
+        validate_display_text!(display_text60, "displayText60", DISPLAY_TEXT_60_MAX_LENGTH)
+      when CONFIRMATION_MESSAGE
+        validate_display_text!(display_text200, "displayText200", DISPLAY_TEXT_200_MAX_LENGTH)
+      else
+        raise SmartIdRuby::Errors::RequestSetupError, "Unsupported interaction type: #{type}"
+      end
+    end
+
+    def validate_display_text!(value, field_name, max_length)
+      if blank?(value)
+        raise SmartIdRuby::Errors::RequestSetupError, "Value for '#{field_name}' cannot be empty"
+      end
+      return if value.to_s.length <= max_length
+
+      raise SmartIdRuby::Errors::RequestSetupError,
+            "Value for '#{field_name}' cannot be longer than #{max_length} characters"
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/smart_id_ruby/errors/certificate_level_mismatch_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when returned certificate level is lower than the requested certificate level.
+    class CertificateLevelMismatchError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/document_unusable_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is DOCUMENT_UNUSABLE.
+    class DocumentUnusableError < Error
+      def initialize(message = "Document is unusable. User must either check his/her Smart-ID mobile application or turn to customer support for getting the exact reason.")
+        super
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Represents  error condition.
+    class Error < SmartIdRuby::Error; end
+  end
+end

data/lib/smart_id_ruby/errors/expected_linked_session_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Linked signature flow consists of two sessions - device link-based certificate choice session followed by the linked signature session.
+    # Exception will be thrown when linked signature session is not received after the device link-based certificate choice session,
+    # but some other session with the same document number is received instead.
+    class ExpectedLinkedSessionError < SessionEndResultError
+      def initialize
+        super("EXPECTED_LINKED_SESSION",
+              "The app received a different transaction while waiting for the linked session that follows the device-link based cert-choice session")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/no_suitable_account_of_requested_type_found_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when user does not have a suitable account for the requested operation.
+    # F.e. user has non-qualified account with ADVANCED certificate level,
+    # but QUALIFIED certificate level is required for the operation.
+    class NoSuitableAccountOfRequestedTypeFoundError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/person_should_view_smart_id_portal_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when Smart-ID API indicates that there is an issue with user document and user should check its state.
+    class PersonShouldViewSmartIdPortalError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/protocol_failure_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Exception thrown when the session status end result is PROTOCOL_FAILURE, indicating logical error in the signing protocol.
+    # F.e. Constructed device link that user can interact with contains invalid schema.
+    class ProtocolFailureError < SessionEndResultError
+      def initialize
+        super("PROTOCOL_FAILURE", "A logical error occurred in the signing protocol.")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/relying_party_account_configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Exception will be thrown when there are problems with relying party account and access configuration
+    # or when relying party does not have access to the requested service.
+    # F.e. Request is made with relying party UUID and incorrect relying party name.
+    class RelyingPartyAccountConfigurationError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/request_setup_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Exception thrown when there is an issue setting up a Smart-ID request.
+    # This could be due to invalid parameters, configuration issues, or other
+    # problems that prevent from successfully preparing the request.
+    class RequestSetupError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/request_validation_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Represents request validation error condition.
+    class RequestValidationError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/required_interaction_not_supported_by_app_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when the user's app version does not support any of the provided interactions.
+    class RequiredInteractionNotSupportedByAppError < SessionEndResultError
+      def initialize
+        super("REQUIRED_INTERACTION_NOT_SUPPORTED_BY_APP",
+              "User app version does not support any of the provided interactions.")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/response_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Represents response error condition.
+    class ResponseError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/server_maintenance_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when request cannot be process because the Smart-ID API server is under maintenance.
+    class ServerMaintenanceError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/session_end_result_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Represents session end result error condition.
+    class SessionEndResultError < Error
+      attr_reader :end_result
+
+      def initialize(end_result, message = nil)
+        @end_result = end_result
+        super(message || "Session ended with result '#{end_result}'")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/session_not_complete_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Represents session not complete error condition.
+    class SessionNotCompleteError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/session_not_found_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session with the given session ID could not be found.
+    class SessionNotFoundError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/session_secret_mismatch_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when the session secret digest from the callback does not match the calculated digest.
+    class SessionSecretMismatchError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/session_timeout_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is TIMEOUT.
+    class SessionTimeoutError < SessionEndResultError
+      def initialize
+        super("TIMEOUT", "Session timed out without getting any response from user")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/smart_id_server_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is SERVER_ERROR, indicating a server-side technical error.
+    class SmartIdServerError < SessionEndResultError
+      def initialize
+        super("SERVER_ERROR", "Process was terminated due to server-side technical error")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/unprocessable_response_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when validation of any Smart-ID API responses fail.
+    # This includes responses for session initialization requests and session status responses.
+    class UnprocessableResponseError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/unsupported_client_api_version_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Represents unsupported client api version error condition.
+    class UnsupportedClientApiVersionError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/user_account_not_found_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when user account does not exist with the given identifier or document number.
+    class UserAccountNotFoundError < Error; end
+  end
+end

data/lib/smart_id_ruby/errors/user_account_unusable_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is ACCOUNT_UNUSABLE.
+    class UserAccountUnusableError < SessionEndResultError
+      def initialize
+        super("ACCOUNT_UNUSABLE", "The account is currently unusable")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/user_refused_cert_choice_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is USER_REFUSED_CERT_CHOICE.
+    # This happens when user has multiple accounts and presses Cancel on device choice screen on any device.
+    class UserRefusedCertChoiceError < SessionEndResultError
+      def initialize
+        super("USER_REFUSED_CERT_CHOICE",
+              "User has multiple accounts and pressed Cancel on device choice screen on any device.")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/user_refused_confirmation_message_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is USER_REFUSED_INTERACTION.
+    # This happens when user presses Cancel on confirmation message screen.
+    class UserRefusedConfirmationMessageError < SessionEndResultError
+      def initialize
+        super("USER_REFUSED_INTERACTION", "User cancelled on confirmationMessage screen")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/user_refused_confirmation_message_with_verification_choice_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is USER_REFUSED_INTERACTION.
+    # This happens when user presses Cancel on confirmation and verification code choice screen.
+    class UserRefusedConfirmationMessageWithVerificationChoiceError < SessionEndResultError
+      def initialize
+        super("USER_REFUSED_INTERACTION", "User cancelled on confirmationMessageAndVerificationCodeChoice screen")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/user_refused_display_text_and_pin_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is USER_REFUSED_INTERACTION.
+    # This happens when user presses Cancel on display text and PIN screen.
+    class UserRefusedDisplayTextAndPinError < SessionEndResultError
+      def initialize
+        super("USER_REFUSED_INTERACTION", "User pressed Cancel on PIN screen.")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/user_refused_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is USER_REFUSED.
+    class UserRefusedError < SessionEndResultError
+      def initialize
+        super("USER_REFUSED", "User pressed cancel in app")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors/user_selected_wrong_verification_code_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Errors
+    # Thrown when session status end result is WRONG_VC.
+    # This happens when user selects wrong verification code in the app.
+    class UserSelectedWrongVerificationCodeError < SessionEndResultError
+      def initialize
+        super("WRONG_VC", "User selected wrong verification code")
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "errors/error"
+require_relative "errors/session_not_found_error"
+require_relative "errors/relying_party_account_configuration_error"
+require_relative "errors/user_account_not_found_error"
+require_relative "errors/server_maintenance_error"
+require_relative "errors/person_should_view_smart_id_portal_error"
+require_relative "errors/no_suitable_account_of_requested_type_found_error"
+require_relative "errors/unsupported_client_api_version_error"
+require_relative "errors/request_validation_error"
+require_relative "errors/request_setup_error"
+require_relative "errors/response_error"
+require_relative "errors/unprocessable_response_error"
+require_relative "errors/document_unusable_error"
+require_relative "errors/certificate_level_mismatch_error"
+require_relative "errors/session_not_complete_error"
+require_relative "errors/session_end_result_error"
+require_relative "errors/session_secret_mismatch_error"
+require_relative "errors/user_refused_error"
+require_relative "errors/session_timeout_error"
+require_relative "errors/user_selected_wrong_verification_code_error"
+require_relative "errors/required_interaction_not_supported_by_app_error"
+require_relative "errors/user_refused_cert_choice_error"
+require_relative "errors/protocol_failure_error"
+require_relative "errors/expected_linked_session_error"
+require_relative "errors/smart_id_server_error"
+require_relative "errors/user_account_unusable_error"
+require_relative "errors/user_refused_display_text_and_pin_error"
+require_relative "errors/user_refused_confirmation_message_error"
+require_relative "errors/user_refused_confirmation_message_with_verification_choice_error"

data/lib/smart_id_ruby/flows/base_builder.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module SmartIdRuby
+  module Flows
+    # Base builder with shared helper methods for request builders.
+    class BaseBuilder
+      attr_reader :connector, :relying_party_uuid, :relying_party_name
+
+      def initialize(connector)
+        @connector = connector
+      end
+
+      def with_relying_party_uuid(value)
+        @relying_party_uuid = value
+        self
+      end
+
+      def with_relying_party_name(value)
+        @relying_party_name = value
+        self
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      def fetch_value(container, key)
+        return nil if container.nil?
+
+        key_str = key.to_s
+        snake_key = underscore_key(key_str)
+        candidates = [key, key_str, snake_key.to_sym, snake_key].uniq
+
+        if container.respond_to?(:[])
+          candidates.each do |candidate|
+            value = container[candidate]
+            return value unless value.nil?
+          end
+        end
+
+        candidates.each do |candidate|
+          method_name = candidate.is_a?(Symbol) ? candidate : candidate.to_s
+          return container.public_send(method_name) if container.respond_to?(method_name)
+        end
+
+        nil
+      end
+
+      def normalize_interactions(interactions)
+        Array(interactions).compact.map { |interaction| normalize_interaction(interaction) }
+      end
+
+      def normalize_interaction(interaction)
+        if interaction.respond_to?(:to_h)
+          interaction.to_h.transform_keys(&:to_sym)
+        elsif interaction.is_a?(Hash)
+          interaction.transform_keys(&:to_sym)
+        else
+          raise SmartIdRuby::Errors::RequestSetupError, "Unsupported interaction object type: #{interaction.class}"
+        end
+      end
+
+      def encode_interactions(interactions)
+        Base64.strict_encode64(JSON.generate(normalize_interactions(interactions)))
+      end
+
+      def normalize_capabilities(capabilities, strip: true, reject_empty: true)
+        values = Array(capabilities).flatten.compact.map(&:to_s)
+        values = values.map(&:strip) if strip
+        values = values.reject(&:empty?) if reject_empty
+        values.uniq
+      end
+
+      def request_properties_for_share_md(share_md_client_ip_address)
+        return nil if share_md_client_ip_address.nil?
+
+        { shareMdClientIpAddress: share_md_client_ip_address }
+      end
+
+      def underscore_key(value)
+        value.to_s.gsub(/([A-Z])/, "_\\1").downcase.sub(/\A_/, "")
+      end
+    end
+  end
+end