smart-id-ruby-client 0.1.0

data/lib/smart_id_ruby/validation/authentication_identity_mapper.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "date"
+require "openssl"
+
+module SmartIdRuby
+  module Validation
+    # Maps authentication certificates to typed identity models.
+    class AuthenticationIdentityMapper
+      # OID for dateOfBirth attribute inside subjectDirectoryAttributes extension (id-pda-dateOfBirth).
+      DATE_OF_BIRTH_OID = "1.3.6.1.5.5.7.9.1"
+      # OID for subjectDirectoryAttributes certificate extension.
+      SUBJECT_DIRECTORY_ATTRIBUTES_OID = "subjectDirectoryAttributes"
+      # OID for X.509 Subject Directory Attributes extension (2.5.29.9).
+      SUBJECT_DIRECTORY_ATTRIBUTES_EXTENSION_OID = "2.5.29.9"
+
+      # Builds an {SmartIdRuby::Models::AuthenticationIdentity} from an
+      # X.509 authentication certificate.
+      #
+      # Extracts given name, surname, national identity number, country and
+      # date of birth (either from certificate extensions or by parsing the
+      # national identity number as a fallback).
+      #
+      # @param certificate [OpenSSL::X509::Certificate]
+      # @return [SmartIdRuby::Models::AuthenticationIdentity]
+      def from(certificate)
+        attrs = extract_subject_attributes(certificate)
+
+        raw_given_name = attrs["GN"] || attrs["givenName"] || attrs["GIVENNAME"]
+        raw_surname = attrs["SN"] || attrs["surname"] || attrs["SURNAME"]
+        identity_number = normalize_identity_number(attrs["serialNumber"] || attrs["SERIALNUMBER"])
+        country = attrs["C"]
+
+        given_name = normalize_diacritics(raw_given_name)
+        surname = normalize_diacritics(raw_surname)
+
+        log_debug_identity_attrs(raw_given_name, given_name, raw_surname, surname, identity_number, country)
+
+        SmartIdRuby::Models::AuthenticationIdentity.new(
+          given_name: given_name,
+          surname: surname,
+          identity_number: identity_number,
+          country: country,
+          auth_certificate: certificate,
+          date_of_birth: extract_date_of_birth_from_certificate(certificate) || fallback_date_of_birth(country, identity_number)
+        )
+      end
+
+      private
+
+      # Extracts subject DN attributes from the certificate into a simple Hash.
+      #
+      # @param certificate [OpenSSL::X509::Certificate]
+      # @return [Hash{String => String}]
+      def extract_subject_attributes(certificate)
+        certificate.subject.to_a.each_with_object({}) do |entry, attrs|
+          key, value = entry[0], entry[1]
+          attrs[key] = value
+        end
+      end
+
+      def normalize_identity_number(serial_number)
+        return nil if serial_number.nil?
+
+        serial_number.split("-", 2).last
+      end
+
+      def fallback_date_of_birth(country, identity_number)
+        return nil if blank?(country) || blank?(identity_number)
+
+        case country.to_s.upcase
+        when "EE", "LT"
+          parse_ee_lt_date_of_birth(identity_number)
+        when "LV"
+          parse_lv_date_of_birth(identity_number)
+        end
+      end
+
+      def parse_ee_lt_date_of_birth(identity_number)
+        first_digit = identity_number[0]
+        birth_date_part = identity_number[1, 6]
+        century = case first_digit
+                  when "1", "2" then "18"
+                  when "3", "4" then "19"
+                  when "5", "6" then "20"
+                  else
+                    raise SmartIdRuby::Errors::UnprocessableResponseError,
+                          "Could not parse birthdate from nationalIdentityNumber=#{identity_number}"
+                  end
+        Date.strptime("#{century}#{birth_date_part}", "%Y%m%d")
+      rescue ArgumentError
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Could not parse birthdate from nationalIdentityNumber=#{identity_number}"
+      end
+
+      def parse_lv_date_of_birth(identity_number)
+        birth_day = identity_number[0, 2]
+        return nil if birth_day.match?(/\A3[2-9]\z/)
+
+        birth_month = identity_number[2, 2]
+        birth_year_two_digit = identity_number[4, 2]
+        century_marker = identity_number[7]
+        century = case century_marker
+                  when "0" then "18"
+                  when "1" then "19"
+                  when "2" then "20"
+                  else
+                    raise SmartIdRuby::Errors::UnprocessableResponseError, "Invalid personal code: #{identity_number}"
+                  end
+
+        Date.strptime("#{century}#{birth_year_two_digit}#{birth_month}#{birth_day}", "%Y%m%d")
+      rescue ArgumentError
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Unable get birthdate from Latvian personal code #{identity_number}"
+      end
+
+      def extract_date_of_birth_from_certificate(certificate)
+        extension = certificate.extensions.find do |ext|
+          [SUBJECT_DIRECTORY_ATTRIBUTES_OID, SUBJECT_DIRECTORY_ATTRIBUTES_EXTENSION_OID].include?(ext.oid)
+        end
+        return nil if extension.nil?
+
+        generalized_time = find_date_of_birth_generalized_time(extension)
+        return nil if generalized_time.nil?
+
+        parse_generalized_time(generalized_time)
+      rescue OpenSSL::ASN1::ASN1Error, TypeError
+        nil
+      end
+
+      def find_date_of_birth_generalized_time(extension)
+        decoded = OpenSSL::ASN1.decode(extension.to_der)
+        octet_string = decoded.value.find { |node| node.is_a?(OpenSSL::ASN1::OctetString) }
+        return nil if octet_string.nil?
+
+        inner = OpenSSL::ASN1.decode(octet_string.value)
+        find_date_of_birth_in_node(inner)
+      end
+
+      def find_date_of_birth_in_node(node)
+        return nil unless node.respond_to?(:value)
+
+        value = node.value
+        return nil unless value.is_a?(Array)
+
+        value.each_with_index do |item, index|
+          if item.is_a?(OpenSSL::ASN1::ObjectId) && item.value == DATE_OF_BIRTH_OID
+            return extract_generalized_time(value[index + 1])
+          end
+          found = find_date_of_birth_in_node(item)
+          return found if found
+        end
+        nil
+      end
+
+      def extract_generalized_time(node)
+        return nil if node.nil? || !node.respond_to?(:value)
+
+        if node.is_a?(OpenSSL::ASN1::GeneralizedTime)
+          return node.value
+        end
+
+        value = node.value
+        return nil unless value.is_a?(Array)
+
+        value.each do |child|
+          found = extract_generalized_time(child)
+          return found if found
+        end
+        nil
+      end
+
+      def parse_generalized_time(value)
+        parsed = if value.respond_to?(:to_time)
+                   value.to_time.utc
+                 else
+                   Time.strptime(value.to_s, "%Y%m%d%H%M%SZ").utc
+                 end
+        parsed.to_date
+      rescue ArgumentError
+        nil
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      # Converts legacy escaped byte sequences inside DN values to proper UTF-8.
+      # Example:
+      #   "J\\xC4\\x81nis B\\xC4\\x93rzi\\xC5\\x86\\xC5\\xA1" (ASCII-8BIT)
+      # becomes:
+      #   "Jānis Bērziņš" (UTF-8)
+      def normalize_diacritics(value)
+        return nil if value.nil?
+
+        text = value.to_s.dup
+
+        # Legacy certificates / libraries sometimes encode diacritics as \xNN escape
+        # sequences in the distinguished name string. Convert those into bytes first.
+        if text.include?("\\x")
+          text = text.gsub(/\\x([0-9A-Fa-f]{2})/) { Regexp.last_match(1).hex.chr }
+        end
+
+        # Then interpret as UTF-8 and scrub only truly invalid byte sequences,
+        # preserving valid characters like Õ, Ä, Ö, Ü, etc.
+        text.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def log_debug_identity_attrs(raw_given_name, given_name, raw_surname, surname, identity_number, country)
+        logger = SmartIdRuby.logger
+
+        logger.debug(
+          "Smart-ID identity mapping: " \
+          "raw_given_name=#{raw_given_name}, " \
+          "normalized_given_name=#{given_name}, " \
+          "raw_surname=#{raw_surname}, " \
+          "normalized_surname=#{surname}, " \
+          "identity_number_suffix=#{identity_number && identity_number[-4, 4]}, " \
+          "country=#{country}"
+        )
+      rescue StandardError
+        # Logging must never break authentication flow
+        nil
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/validation/base_authentication_response_validator.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+
+module SmartIdRuby
+  module Validation
+    # Shared authentication response validation logic for device-link and notification flows.
+    class BaseAuthenticationResponseValidator
+      BASE64_FORMAT_PATTERN = /\A[a-zA-Z0-9+\/]+={0,2}\z/.freeze
+      USER_CHALLENGE_PATTERN = /\A[a-zA-Z0-9\-_]{43}\z/.freeze
+      MINIMUM_SERVER_RANDOM_LENGTH = 24
+      SUPPORTED_FLOW_TYPES = %w[QR Web2App App2App Notification].freeze
+      SUPPORTED_SIGNATURE_ALGORITHM = "rsassa-pss"
+      SUPPORTED_HASH_ALGORITHM_OCTET_LENGTH = {
+        "SHA-256" => 32,
+        "SHA-384" => 48,
+        "SHA-512" => 64,
+        "SHA3-256" => 32,
+        "SHA3-384" => 48,
+        "SHA3-512" => 64
+      }.freeze
+      SUPPORTED_MASK_GEN_ALGORITHM = "id-mgf1"
+      SUPPORTED_TRAILER_FIELD = "0xbc"
+
+      def initialize(signature_value_validator: SignatureValueValidator.new,
+                     certificate_validator: AuthenticationCertificateValidator.new,
+                     authentication_identity_mapper: AuthenticationIdentityMapper.new)
+        @signature_value_validator = signature_value_validator
+        @certificate_validator = certificate_validator
+        @authentication_identity_mapper = authentication_identity_mapper
+      end
+
+      def validate(session_status, authentication_session_request, user_challenge_verifier = nil, schema_name = nil,
+                   brokered_rp_name = nil)
+        status = normalize_status(session_status)
+        validate_inputs(status, authentication_session_request, schema_name)
+        validate_complete_state(status)
+        validate_result(status.result)
+        validate_signature_protocol(status)
+        validate_signature(status.signature)
+        validate_user_challenge(user_challenge_verifier, status.signature)
+        certificate = @certificate_validator.validate(
+          cert: status.cert,
+          requested_level: requested_certificate_level(authentication_session_request)
+        )
+        validate_signature_value(status, authentication_session_request, schema_name, brokered_rp_name, certificate)
+        validate_interaction_type(status)
+
+        @authentication_identity_mapper.from(certificate)
+      end
+
+      private
+
+      def normalize_status(session_status)
+        return session_status if session_status.is_a?(SmartIdRuby::Models::SessionStatus)
+        return SmartIdRuby::Models::SessionStatus.from_h(session_status) if session_status.is_a?(Hash)
+
+        nil
+      end
+
+      def validate_inputs(session_status, authentication_session_request, schema_name)
+        raise SmartIdRuby::Errors::RequestSetupError, "Parameter 'sessionStatus' is not provided" if session_status.nil?
+        if authentication_session_request.nil?
+          raise SmartIdRuby::Errors::RequestSetupError, "Parameter 'authenticationSessionRequest' is not provided"
+        end
+        return unless blank?(schema_name)
+
+        raise SmartIdRuby::Errors::RequestSetupError, "Parameter 'schemaName' is not provided"
+      end
+
+      def validate_complete_state(session_status)
+        return if session_status.complete?
+
+        raise SmartIdRuby::Errors::SessionNotCompleteError,
+              "Authentication session is not complete. Current state: '#{session_status.state}'"
+      end
+
+      def validate_result(result)
+        if result.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Authentication session status field 'result' is empty"
+        end
+        if blank?(result.end_result)
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Authentication session status field 'result.endResult' is empty"
+        end
+
+        ErrorResultHandler.handle(result) if result.end_result != "OK"
+        return unless blank?(result.document_number)
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError, "Authentication session status field 'result.documentNumber' is empty"
+      end
+
+      def validate_signature_protocol(session_status)
+        if blank?(session_status.signature_protocol)
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Authentication session status field 'signatureProtocol' is empty"
+        end
+        return if session_status.signature_protocol == "ACSP_V2"
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Authentication session status field 'signatureProtocol' has unsupported value"
+      end
+
+      def validate_signature(signature)
+        if signature.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature' is missing"
+        end
+        validate_base64_field(signature.value, "signature.value")
+        validate_server_random(signature.server_random)
+        validate_user_challenge_format(signature.user_challenge)
+        validate_non_empty(signature.flow_type, "signature.flowType")
+        unless SUPPORTED_FLOW_TYPES.include?(signature.flow_type)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.flowType' has unsupported value"
+        end
+        validate_non_empty(signature.signature_algorithm, "signature.signatureAlgorithm")
+        unless signature.signature_algorithm == SUPPORTED_SIGNATURE_ALGORITHM
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithm' has unsupported value"
+        end
+        validate_signature_algorithm_parameters(signature.signature_algorithm_parameters)
+      end
+
+      def validate_interaction_type(session_status)
+        return unless blank?(session_status.interaction_type_used)
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Authentication session status field 'interactionTypeUsed' is empty"
+      end
+
+      def validate_base64_field(value, field_name)
+        validate_non_empty(value, field_name)
+        return if BASE64_FORMAT_PATTERN.match?(value)
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Authentication session status field '#{field_name}' does not have Base64-encoded value"
+      end
+
+      def validate_server_random(value)
+        validate_non_empty(value, "signature.serverRandom")
+        if value.length < MINIMUM_SERVER_RANDOM_LENGTH
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.serverRandom' value length is less than required"
+        end
+        validate_base64_field(value, "signature.serverRandom")
+      end
+
+      def validate_user_challenge_format(value)
+        validate_non_empty(value, "signature.userChallenge")
+        return if USER_CHALLENGE_PATTERN.match?(value)
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Authentication session status field 'signature.userChallenge' value does not match required pattern"
+      end
+
+      def validate_user_challenge(_user_challenge_verifier, _signature); end
+
+      def validate_signature_algorithm_parameters(signature_algorithm_parameters)
+        if signature_algorithm_parameters.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters' is missing"
+        end
+
+        hash_algorithm = signature_algorithm_parameters.hash_algorithm
+        if blank?(hash_algorithm)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.hashAlgorithm' is empty"
+        end
+        unless SUPPORTED_HASH_ALGORITHM_OCTET_LENGTH.key?(hash_algorithm)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.hashAlgorithm' has unsupported value"
+        end
+
+        mask_gen_algorithm = signature_algorithm_parameters.mask_gen_algorithm
+        if mask_gen_algorithm.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm' is missing"
+        end
+        mask_gen_algorithm_value = fetch_hash_value(mask_gen_algorithm, :algorithm)
+        if blank?(mask_gen_algorithm_value)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.algorithm' is empty"
+        end
+        unless mask_gen_algorithm_value == SUPPORTED_MASK_GEN_ALGORITHM
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm' has unsupported value"
+        end
+
+        mask_gen_parameters = fetch_hash_value(mask_gen_algorithm, :parameters)
+        if mask_gen_parameters.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters' is missing"
+        end
+        mask_hash_algorithm = fetch_hash_value(mask_gen_parameters, :hashAlgorithm)
+        if blank?(mask_hash_algorithm)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' is empty"
+        end
+        unless SUPPORTED_HASH_ALGORITHM_OCTET_LENGTH.key?(mask_hash_algorithm)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' has unsupported value"
+        end
+        unless hash_algorithm == mask_hash_algorithm
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.hashAlgorithm' value does not match 'signature.signatureAlgorithmParameters.hashAlgorithm' value"
+        end
+
+        salt_length = signature_algorithm_parameters.salt_length
+        if salt_length.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.saltLength' is empty"
+        end
+        unless salt_length == SUPPORTED_HASH_ALGORITHM_OCTET_LENGTH[hash_algorithm]
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.saltLength' has invalid value"
+        end
+
+        trailer_field = signature_algorithm_parameters.trailer_field
+        if blank?(trailer_field)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'signature.signatureAlgorithmParameters.trailerField' is empty"
+        end
+        return if trailer_field == SUPPORTED_TRAILER_FIELD
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Authentication session status field 'signature.signatureAlgorithmParameters.trailerField' has unsupported value"
+      end
+
+      def validate_signature_value(session_status, authentication_session_request, schema_name, brokered_rp_name, certificate)
+        payload = build_signature_payload(session_status, authentication_session_request, schema_name, brokered_rp_name)
+        @signature_value_validator.validate(
+          signature_value: session_status.signature.value,
+          payload: payload,
+          certificate: certificate,
+          signature_algorithm_parameters: session_status.signature.signature_algorithm_parameters
+        )
+      end
+
+      def build_signature_payload(session_status, authentication_session_request, schema_name, brokered_rp_name)
+        signature_protocol_parameters = fetch_request_value(authentication_session_request, :signatureProtocolParameters)
+        rp_challenge = fetch_hash_value(signature_protocol_parameters, :rpChallenge)
+        relying_party_name = fetch_request_value(authentication_session_request, :relyingPartyName)
+        interactions = fetch_request_value(authentication_session_request, :interactions)
+
+        [
+          schema_name,
+          "ACSP_V2",
+          session_status.signature.server_random,
+          rp_challenge,
+          session_status.signature.user_challenge || "",
+          to_base64_utf8(relying_party_name),
+          blank?(brokered_rp_name) ? "" : to_base64_utf8(brokered_rp_name),
+          calculate_interactions_digest(interactions),
+          session_status.interaction_type_used,
+          callback_url_segment(session_status, authentication_session_request),
+          session_status.signature.flow_type
+        ].join("|")
+      end
+
+      def callback_url_segment(_session_status, _authentication_session_request)
+        ""
+      end
+
+      def requested_certificate_level(authentication_session_request)
+        value = fetch_request_value(authentication_session_request, :certificateLevel)
+        return "QUALIFIED" if blank?(value)
+
+        value
+      end
+
+      def fetch_request_value(payload, key)
+        return nil unless payload.respond_to?(:[])
+
+        payload[key] || payload[key.to_s]
+      end
+
+      def fetch_hash_value(payload, key)
+        return nil unless payload.respond_to?(:[])
+
+        payload[key] || payload[key.to_s]
+      end
+
+      def calculate_interactions_digest(interactions)
+        digest = OpenSSL::Digest::SHA256.digest(interactions.to_s)
+        Base64.strict_encode64(digest)
+      end
+
+      def to_base64_utf8(input)
+        Base64.strict_encode64(input.to_s.encode("UTF-8"))
+      end
+
+      def validate_non_empty(value, field_name)
+        return unless blank?(value)
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Authentication session status field '#{field_name}' is empty"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/validation/certificate_choice_response_validator.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+
+module SmartIdRuby
+  module Validation
+    # Validates certificate choice response data.
+    class CertificateChoiceResponseValidator
+      CERTIFICATE_LEVEL_ORDER = { "ADVANCED" => 1, "QUALIFIED" => 2, "QSCD" => 2 }.freeze
+
+      def initialize(certificate_validator: CertificateValidator.new)
+        @certificate_validator = certificate_validator
+      end
+
+      def validate(session_status, requested_certificate_level = "QUALIFIED")
+        status = normalize_status(session_status)
+        raise SmartIdRuby::Errors::RequestSetupError, "Parameter 'sessionStatus' is not provided" if status.nil?
+        if requested_certificate_level.nil?
+          raise SmartIdRuby::Errors::RequestSetupError, "Parameter 'requestedCertificateLevel' is not provided"
+        end
+
+        validate_result(status.result)
+        certificate_level, certificate = validate_session_status_certificate(status.cert, requested_certificate_level)
+        to_certificate_choice_response(status, certificate, certificate_level)
+      end
+
+      private
+
+      def validate_result(session_result)
+        if session_result.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate choice session status field 'result' is missing"
+        end
+        if blank?(session_result.end_result)
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate choice session status field 'result.endResult' is empty"
+        end
+
+        ErrorResultHandler.handle(session_result) unless session_result.end_result == "OK"
+        return unless blank?(session_result.document_number)
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Certificate choice session status field 'result.documentNumber' is empty"
+      end
+
+      def validate_session_status_certificate(session_certificate, requested_certificate_level)
+        if session_certificate.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate choice session status field 'cert' is missing"
+        end
+        if blank?(session_certificate.value)
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate choice session status field 'cert.value' has empty value"
+        end
+        if blank?(session_certificate.certificate_level)
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate choice session status field 'cert.certificateLevel' has empty value"
+        end
+
+        unless CERTIFICATE_LEVEL_ORDER.key?(session_certificate.certificate_level)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Certificate choice session status field 'cert.certificateLevel' has unsupported value"
+        end
+
+        response_level = session_certificate.certificate_level
+        requested_level = requested_certificate_level.to_s
+        requested_level = "QUALIFIED" if requested_level.strip.empty?
+        if CERTIFICATE_LEVEL_ORDER[response_level] < CERTIFICATE_LEVEL_ORDER.fetch(requested_level, CERTIFICATE_LEVEL_ORDER["QUALIFIED"])
+          raise SmartIdRuby::Errors::CertificateLevelMismatchError,
+                "Certificate choice session status response certificate level is lower than requested"
+        end
+
+        certificate = parse_certificate(session_certificate.value)
+        @certificate_validator&.validate(certificate)
+        [response_level, certificate]
+      end
+
+      def parse_certificate(cert_base64)
+        decoded = Base64.decode64(cert_base64.to_s)
+        OpenSSL::X509::Certificate.new(decoded)
+      rescue OpenSSL::X509::CertificateError, ArgumentError
+        raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate is invalid"
+      end
+
+      def to_certificate_choice_response(status, certificate, certificate_level)
+        SmartIdRuby::Models::CertificateChoiceResponse.new(
+          end_result: status.result.end_result,
+          document_number: status.result.document_number,
+          certificate: certificate,
+          certificate_level: certificate_level,
+          interaction_flow_used: status.interaction_type_used,
+          device_ip_address: status.device_ip_address
+        )
+      end
+
+      def normalize_status(session_status)
+        return session_status if session_status.respond_to?(:result)
+        return SmartIdRuby::Models::SessionStatus.from_h(session_status) if session_status.is_a?(Hash)
+
+        nil
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end