smart-id-ruby-client 0.1.0

data/lib/smart_id_ruby/rest/connector.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "faraday"
+require "uri"
+
+module SmartIdRuby
+  module Rest
+    # Smart-ID REST connector implementation for RP API v3.1.
+    class Connector
+      SESSION_STATUS_PATH = "session/%<session_id>s"
+
+      DEVICE_LINK_CERTIFICATE_CHOICE_DEVICE_LINK_PATH = "signature/certificate-choice/device-link/anonymous"
+      LINKED_NOTIFICATION_SIGNATURE_WITH_DOCUMENT_NUMBER_PATH = "signature/notification/linked/%<document_number>s"
+      NOTIFICATION_CERTIFICATE_CHOICE_WITH_SEMANTIC_IDENTIFIER_PATH = "signature/certificate-choice/notification/etsi/%<semantics_identifier>s"
+      CERTIFICATE_BY_DOCUMENT_NUMBER_PATH = "signature/certificate/%<document_number>s"
+      DEVICE_LINK_SIGNATURE_WITH_SEMANTIC_IDENTIFIER_PATH = "signature/device-link/etsi/%<semantics_identifier>s"
+      DEVICE_LINK_SIGNATURE_WITH_DOCUMENT_NUMBER_PATH = "signature/device-link/document/%<document_number>s"
+      NOTIFICATION_SIGNATURE_WITH_SEMANTIC_IDENTIFIER_PATH = "signature/notification/etsi/%<semantics_identifier>s"
+      NOTIFICATION_SIGNATURE_WITH_DOCUMENT_NUMBER_PATH = "signature/notification/document/%<document_number>s"
+      ANONYMOUS_DEVICE_LINK_AUTHENTICATION_PATH = "authentication/device-link/anonymous"
+      DEVICE_LINK_AUTHENTICATION_WITH_SEMANTIC_IDENTIFIER_PATH = "authentication/device-link/etsi/%<semantics_identifier>s"
+      DEVICE_LINK_AUTHENTICATION_WITH_DOCUMENT_NUMBER_PATH = "authentication/device-link/document/%<document_number>s"
+      NOTIFICATION_AUTHENTICATION_WITH_SEMANTIC_IDENTIFIER_PATH = "authentication/notification/etsi/%<semantics_identifier>s"
+      NOTIFICATION_AUTHENTICATION_WITH_DOCUMENT_NUMBER_PATH = "authentication/notification/document/%<document_number>s"
+
+      attr_reader :host_url, :configured_connection, :network_connection_config, :ssl_context
+
+      def initialize(host_url:, configured_connection: nil, network_connection_config: nil, ssl_context: nil)
+        @host_url = host_url
+        @configured_connection = configured_connection
+        @network_connection_config = network_connection_config
+        @ssl_context = ssl_context
+        @session_status_response_socket_open_time = nil
+      end
+
+      def set_session_status_response_socket_open_time(unit, value)
+        @session_status_response_socket_open_time = { unit: unit, value: value }
+      end
+
+      def session_status_response_socket_open_time
+        @session_status_response_socket_open_time
+      end
+
+      def set_ssl_context(ssl_context)
+        @ssl_context = ssl_context
+        @connection = nil
+      end
+
+      def get_session_status(session_id)
+        logger.debug("Getting session status for sessionId: #{session_id}")
+        query = {}
+        if @session_status_response_socket_open_time && @session_status_response_socket_open_time[:value].to_i.positive?
+          query["timeoutMs"] = to_milliseconds(
+            @session_status_response_socket_open_time[:unit],
+            @session_status_response_socket_open_time[:value]
+          )
+        end
+
+        path = format(SESSION_STATUS_PATH, session_id: encode_path_segment(session_id))
+        response = get(path, query: query, not_found_error: SmartIdRuby::Errors::SessionNotFoundError)
+        SmartIdRuby::Models::SessionStatus.from_h(response)
+      end
+
+      def init_device_link_authentication(authentication_request, semantics_identifier)
+        logger.debug("Starting device link authentication session with semantics identifier")
+        path = format(
+          DEVICE_LINK_AUTHENTICATION_WITH_SEMANTIC_IDENTIFIER_PATH,
+          semantics_identifier: encode_path_segment(extract_identifier(semantics_identifier))
+        )
+        post(path, body: authentication_request)
+      end
+
+      def init_device_link_authentication_with_document(authentication_request, document_number)
+        logger.debug("Starting device link authentication session with document number")
+        path = format(
+          DEVICE_LINK_AUTHENTICATION_WITH_DOCUMENT_NUMBER_PATH,
+          document_number: encode_path_segment(document_number)
+        )
+        post(path, body: authentication_request)
+      end
+
+      def init_anonymous_device_link_authentication(authentication_request)
+        logger.debug("Starting anonymous device link authentication session")
+        post(ANONYMOUS_DEVICE_LINK_AUTHENTICATION_PATH, body: authentication_request)
+      end
+
+      def init_notification_authentication(authentication_request, semantics_identifier)
+        logger.debug("Starting notification authentication session with semantics identifier")
+        path = format(
+          NOTIFICATION_AUTHENTICATION_WITH_SEMANTIC_IDENTIFIER_PATH,
+          semantics_identifier: encode_path_segment(extract_identifier(semantics_identifier))
+        )
+        post(path, body: authentication_request)
+      end
+
+      def init_notification_authentication_with_document(authentication_request, document_number)
+        logger.debug("Starting notification authentication session with document number")
+        path = format(
+          NOTIFICATION_AUTHENTICATION_WITH_DOCUMENT_NUMBER_PATH,
+          document_number: encode_path_segment(document_number)
+        )
+        post(path, body: authentication_request)
+      end
+
+      def init_device_link_certificate_choice(request)
+        logger.debug("Initiating device link based certificate choice request")
+        post(DEVICE_LINK_CERTIFICATE_CHOICE_DEVICE_LINK_PATH, body: request)
+      end
+
+      def init_linked_notification_signature(request, document_number)
+        logger.debug("Starting linked notification-based signature session")
+        path = format(
+          LINKED_NOTIFICATION_SIGNATURE_WITH_DOCUMENT_NUMBER_PATH,
+          document_number: encode_path_segment(document_number)
+        )
+        post(path, body: request)
+      end
+
+      def init_notification_certificate_choice(request, semantics_identifier)
+        logger.debug("Starting notification-based certificate choice session")
+        path = format(
+          NOTIFICATION_CERTIFICATE_CHOICE_WITH_SEMANTIC_IDENTIFIER_PATH,
+          semantics_identifier: encode_path_segment(extract_identifier(semantics_identifier))
+        )
+        post(path, body: request)
+      end
+
+      def get_certificate_by_document_number(document_number, request)
+        logger.debug("Querying certificate by document number")
+        path = format(CERTIFICATE_BY_DOCUMENT_NUMBER_PATH, document_number: encode_path_segment(document_number))
+        post(path, body: request)
+      end
+
+      def init_device_link_signature(request, semantics_identifier)
+        logger.debug("Starting device link signature session with semantics identifier")
+        path = format(
+          DEVICE_LINK_SIGNATURE_WITH_SEMANTIC_IDENTIFIER_PATH,
+          semantics_identifier: encode_path_segment(extract_identifier(semantics_identifier))
+        )
+        post(path, body: request)
+      end
+
+      def init_device_link_signature_with_document(request, document_number)
+        logger.debug("Starting device link signature session with document number")
+        path = format(
+          DEVICE_LINK_SIGNATURE_WITH_DOCUMENT_NUMBER_PATH,
+          document_number: encode_path_segment(document_number)
+        )
+        post(path, body: request)
+      end
+
+      def init_notification_signature(request, semantics_identifier)
+        logger.debug("Starting notification signature session with semantics identifier")
+        path = format(
+          NOTIFICATION_SIGNATURE_WITH_SEMANTIC_IDENTIFIER_PATH,
+          semantics_identifier: encode_path_segment(extract_identifier(semantics_identifier))
+        )
+        post(path, body: request)
+      end
+
+      def init_notification_signature_with_document(request, document_number)
+        logger.debug("Starting notification signature session with document number")
+        path = format(
+          NOTIFICATION_SIGNATURE_WITH_DOCUMENT_NUMBER_PATH,
+          document_number: encode_path_segment(document_number)
+        )
+        post(path, body: request)
+      end
+
+      private
+
+      def connection
+        @connection ||= configured_connection ||
+                        Faraday.new(url: host_url, ssl: ssl_options) do |faraday|
+                          apply_connection_config(faraday)
+                          faraday.response :raise_error
+                          faraday.adapter Faraday.default_adapter
+                        end
+      end
+
+      def ssl_options
+        options = { verify: true }
+        return options unless ssl_context.respond_to?(:cert_store)
+
+        cert_store = ssl_context.cert_store
+        options[:cert_store] = cert_store if cert_store
+        options
+      end
+
+      def apply_connection_config(faraday)
+        return unless network_connection_config.is_a?(Hash)
+
+        headers = network_connection_config[:headers]
+        faraday.headers.update(headers) if headers.is_a?(Hash)
+
+        request_opts = network_connection_config[:request]
+        configure_request_options(faraday.options, request_opts) if request_opts.is_a?(Hash)
+
+        configure_request_options(faraday.options, network_connection_config)
+      end
+
+      def configure_request_options(options, config)
+        timeout = config[:timeout]
+        open_timeout = config[:open_timeout]
+        write_timeout = config[:write_timeout]
+
+        options.timeout = timeout if timeout
+        options.open_timeout = open_timeout if open_timeout
+        options.write_timeout = write_timeout if write_timeout && options.respond_to?(:write_timeout=)
+      end
+
+      def get(path, query:, not_found_error: nil)
+        response = perform_request(:get, path, query: query)
+        parse_response(response)
+      rescue Faraday::ResourceNotFound
+        logger.warn("Session or resource not found for path #{path}")
+        raise(not_found_error || SmartIdRuby::Errors::UserAccountNotFoundError)
+      rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
+        logger.warn("Request is unauthorized for path #{path}: #{e.message}")
+        raise SmartIdRuby::Errors::RelyingPartyAccountConfigurationError, e.message
+      rescue Faraday::ClientError => e
+        handle_client_error(e)
+      rescue Faraday::ServerError => e
+        handle_server_error(e)
+      end
+
+      def post(path, body:)
+        response = perform_request(:post, path, body: body)
+        parse_response(response)
+      rescue Faraday::ResourceNotFound
+        logger.warn("User account not found for path #{path}")
+        raise SmartIdRuby::Errors::UserAccountNotFoundError
+      rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
+        logger.warn("No permission to issue request for path #{path}: #{e.message}")
+        raise SmartIdRuby::Errors::RelyingPartyAccountConfigurationError, e.message
+      rescue Faraday::BadRequestError => e
+        logger.warn("Request is invalid for path #{path}: #{e.message}")
+        raise SmartIdRuby::Errors::RequestValidationError, e.message
+      rescue Faraday::ClientError => e
+        handle_client_error(e)
+      rescue Faraday::ServerError => e
+        handle_server_error(e)
+      end
+
+      def perform_request(method, path, query: nil, body: nil)
+        url = build_url(path)
+        headers = default_headers
+        logger.debug("#{method.to_s.upcase} #{url}")
+        if method == :post && logger.respond_to?(:debug?) && logger.debug?
+          logger.debug("Request body: #{safe_json_for_log(body)}")
+        end
+
+        response = if method == :get
+                     connection.get(url, query, headers)
+                   else
+                     connection.post(url, JSON.generate(body), headers)
+                   end
+        logger.debug("Response status: #{response.status}")
+        logger.debug("Response body: #{truncate_for_log(response.body)}")
+        response
+      end
+
+      def build_url(path)
+        normalized_path = path.to_s.sub(%r{\A/+}, "")
+        URI.join(host_url, normalized_path).to_s
+      end
+
+      def default_headers
+        {
+          "Accept" => "application/json",
+          "Content-Type" => "application/json",
+          "User-Agent" => "smart_id/#{SmartIdRuby::VERSION} (Ruby/#{RUBY_VERSION})"
+        }
+      end
+
+      def parse_response(response)
+        return {} if response.body.nil? || response.body.to_s.strip.empty?
+        return response.body if response.body.is_a?(Hash)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise SmartIdRuby::Errors::ResponseError, "Failed to parse Smart-ID response body: #{e.message}"
+      end
+
+      def handle_client_error(error)
+        status = error.response[:status].to_i
+        logger.debug("Client error response status=#{status}, body=#{truncate_for_log(error.response[:body])}")
+        case status
+        when 471
+          logger.warn("No suitable account of requested type found, but user has some other accounts")
+          raise SmartIdRuby::Errors::NoSuitableAccountOfRequestedTypeFoundError
+        when 472
+          logger.warn("Person should view Smart-ID app or Smart-ID self-service portal now")
+          raise SmartIdRuby::Errors::PersonShouldViewSmartIdPortalError
+        when 480
+          logger.warn("Client-side API is too old and not supported anymore")
+          raise SmartIdRuby::Errors::UnsupportedClientApiVersionError
+        else
+          logger.warn("Server refused the request: #{error.message}")
+          raise SmartIdRuby::Errors::RequestValidationError, error.message
+        end
+      end
+
+      def handle_server_error(error)
+        status = error.response[:status].to_i
+        logger.debug("Server error response status=#{status}, body=#{truncate_for_log(error.response[:body])}")
+        if status == 580
+          logger.warn("Server is under maintenance, retry later")
+          raise SmartIdRuby::Errors::ServerMaintenanceError
+        end
+
+        logger.warn("Unexpected server error: #{error.message}")
+        raise SmartIdRuby::Errors::ResponseError, error.message
+      end
+
+      def extract_identifier(semantics_identifier)
+        return semantics_identifier.identifier if semantics_identifier.respond_to?(:identifier)
+
+        semantics_identifier
+      end
+
+      def encode_path_segment(value)
+        CGI.escape(value.to_s).gsub("+", "%20")
+      end
+
+      def to_milliseconds(unit, value)
+        numeric = value.to_i
+        return numeric if numeric <= 0
+
+        case unit.to_sym
+        when :milliseconds
+          numeric
+        when :seconds
+          numeric * 1000
+        when :minutes
+          numeric * 60_000
+        when :hours
+          numeric * 3_600_000
+        else
+          numeric
+        end
+      end
+
+      def logger
+        SmartIdRuby.logger
+      end
+
+      def safe_json_for_log(value)
+        json = JSON.generate(value)
+        truncate_for_log(json)
+      rescue StandardError
+        "<unserializable request body>"
+      end
+
+      def truncate_for_log(value, max = 2_000)
+        text = value.is_a?(String) ? value : value.inspect
+        return text if text.length <= max
+
+        "#{text[0, max]}...(truncated #{text.length - max} chars)"
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/rest/session_status_poller.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  module Rest
+    # Provides methods for querying session status and polling session status.
+    class SessionStatusPoller
+      DEFAULT_MAX_POLL_DURATION_SECONDS = 300
+
+      def initialize(connector)
+        @connector = connector
+        @polling_sleep_time_unit = :seconds
+        @polling_sleep_timeout = 1
+        @max_poll_duration_seconds = DEFAULT_MAX_POLL_DURATION_SECONDS
+      end
+
+      def set_polling_sleep_time(unit, timeout)
+        logger.debug("Setting polling sleep time to #{timeout} #{unit}")
+        @polling_sleep_time_unit = unit
+        @polling_sleep_timeout = timeout
+      end
+
+      def set_max_poll_duration(unit, timeout)
+        seconds = convert_to_seconds(unit, timeout.to_f)
+        @max_poll_duration_seconds = seconds.positive? ? seconds : 0
+      end
+
+      def polling_sleep_time
+        { unit: @polling_sleep_time_unit, timeout: @polling_sleep_timeout }
+      end
+
+      # Loops session status query until state is COMPLETE.
+      def fetch_final_session_status(session_id)
+        logger.debug("Starting to poll session status for session #{session_id}")
+        poll_for_final_session_status(session_id)
+      rescue Interrupt => e
+        logger.error("Failed to poll session status: #{e.message}")
+        raise SmartIdRuby::Error, "Failed to poll session status"
+      end
+
+      # Query session status once.
+      def get_session_status(session_id)
+        logger.debug("Querying session status")
+        @connector.get_session_status(session_id)
+      end
+
+      private
+
+      def poll_for_final_session_status(session_id)
+        started_at = monotonic_now
+        session_status = nil
+        while session_status.nil? || running?(session_status)
+          enforce_max_poll_duration!(started_at, session_id)
+          session_status = get_session_status(session_id)
+          break if complete?(session_status)
+
+          logger.debug("Sleeping for #{@polling_sleep_timeout} #{@polling_sleep_time_unit}")
+          sleep_for_poll_interval
+        end
+        logger.debug("Got final session status response")
+        session_status
+      end
+
+      def running?(session_status)
+        session_state(session_status)&.casecmp("RUNNING")&.zero?
+      end
+
+      def complete?(session_status)
+        session_state(session_status)&.casecmp("COMPLETE")&.zero?
+      end
+
+      def session_state(session_status)
+        if session_status.respond_to?(:[])
+          session_status[:state] || session_status["state"]
+        elsif session_status.respond_to?(:state)
+          session_status.state
+        end
+      end
+
+      def sleep_for_poll_interval
+        seconds = poll_interval_in_seconds
+        return if seconds <= 0
+
+        sleep(seconds)
+      end
+
+      def enforce_max_poll_duration!(started_at, session_id)
+        return if @max_poll_duration_seconds.nil? || @max_poll_duration_seconds <= 0
+        return if (monotonic_now - started_at) <= @max_poll_duration_seconds
+
+        raise SmartIdRuby::Errors::SessionNotCompleteError,
+              "Session #{session_id} did not complete within #{@max_poll_duration_seconds} seconds"
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def poll_interval_in_seconds
+        timeout = @polling_sleep_timeout.to_f
+        return 0 if timeout <= 0
+
+        convert_to_seconds(@polling_sleep_time_unit, timeout)
+      end
+
+      def convert_to_seconds(unit, timeout)
+        case unit&.to_sym
+        when :milliseconds
+          timeout / 1000.0
+        when :seconds
+          timeout
+        when :minutes
+          timeout * 60
+        when :hours
+          timeout * 3600
+        else
+          timeout
+        end
+      end
+
+      def logger
+        SmartIdRuby.logger
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/rp_challenge.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module SmartIdRuby
+  # Represents RP challenge bytes and helper encodings.
+  class RpChallenge
+    def initialize(value)
+      @value = normalize_value(value).freeze
+    end
+
+    # Returns a copy of the challenge bytes.
+    def value
+      @value.dup
+    end
+
+    # Returns challenge as a Base64-encoded string.
+    def to_base64_encoded_value
+      Base64.strict_encode64(@value)
+    end
+
+    private
+
+    # Accepts Ruby-friendly inputs and normalizes them into binary bytes.
+    def normalize_value(input)
+      case input
+      when String
+        input.dup.force_encoding(Encoding::BINARY)
+      when Array
+        input.pack("C*")
+      else
+        raise SmartIdRuby::Errors::RequestValidationError,
+              "Value for 'value' must be a binary String or an Array of bytes"
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/rp_challenge_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SmartIdRuby
+  # Utility class for generating RP challenges.
+  class RpChallengeGenerator
+    MAX_LENGTH = 64
+    MIN_LENGTH = 32
+
+    class << self
+      # Generates an RP challenge with default length (64 bytes).
+      def generate(length = MAX_LENGTH)
+        validate_length!(length)
+        RpChallenge.new(SecureRandom.random_bytes(length))
+      end
+
+      private
+
+      def validate_length!(length)
+        return if length.is_a?(Integer) && length.between?(MIN_LENGTH, MAX_LENGTH)
+
+        raise SmartIdRuby::Errors::RequestValidationError,
+              "Length must be between #{MIN_LENGTH} and #{MAX_LENGTH}"
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/semantics_identifier.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  # Representation of Semantic Identifier.
+  class SemanticsIdentifier
+    module IdentityType
+      PAS = "PAS"
+      IDC = "IDC"
+      PNO = "PNO"
+    end
+
+    module CountryCode
+      EE = "EE"
+      LT = "LT"
+      LV = "LV"
+    end
+
+    attr_reader :identifier
+
+    # Supports:
+    # - SemanticsIdentifier.new("PNO", "EE", "30303039914")
+    # - SemanticsIdentifier.new("PNOEE-30303039914")
+    def initialize(identity_type_or_identifier, country_code = nil, identity_number = nil)
+      @identifier =
+        if country_code.nil? && identity_number.nil?
+          identity_type_or_identifier
+        elsif !country_code.nil? && !identity_number.nil?
+          "#{identity_type_or_identifier}#{country_code}-#{identity_number}"
+        else
+          raise SmartIdRuby::Errors::RequestValidationError,
+                "Provide either full identifier or identityType + countryCode + identityNumber"
+        end
+    end
+  end
+end

data/lib/smart_id_ruby/validation/authentication_certificate_validator.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+
+module SmartIdRuby
+  module Validation
+    # Validates authentication certificate structure, level and purpose.
+    class AuthenticationCertificateValidator
+      QUALIFIED_CERTIFICATE_POLICY_OIDS = ["1.3.6.1.4.1.10015.17.2", "0.4.0.2042.1.2"].freeze
+      CERTIFICATE_LEVEL_ORDER = {
+        "ADVANCED" => 1,
+        "QUALIFIED" => 2,
+        "QSCD" => 3
+      }.freeze
+
+      def validate(cert:, requested_level:)
+        if cert.nil?
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Authentication session status field 'cert' is missing"
+        end
+
+        validate_non_empty(cert.value, "cert.value")
+        validate_non_empty(cert.certificate_level, "cert.certificateLevel")
+
+        actual_level = cert.certificate_level.to_s.upcase
+        required_level = requested_level.to_s.upcase
+        unless CERTIFICATE_LEVEL_ORDER.key?(actual_level)
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Authentication session status field 'cert.certificateLevel' has unsupported value"
+        end
+        unless CERTIFICATE_LEVEL_ORDER[actual_level] >= CERTIFICATE_LEVEL_ORDER.fetch(required_level, 2)
+          raise SmartIdRuby::Errors::UnprocessableResponseError, "Signer's certificate is below requested certificate level"
+        end
+
+        certificate = parse_certificate(cert.value)
+        validate_certificate_is_currently_valid(certificate)
+        validate_certificate_purpose(certificate, actual_level)
+        certificate
+      end
+
+      private
+
+      def parse_certificate(value)
+        der = Base64.decode64(value)
+        OpenSSL::X509::Certificate.new(der)
+      rescue OpenSSL::X509::CertificateError, ArgumentError
+        raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate is invalid"
+      end
+
+      def validate_certificate_is_currently_valid(certificate)
+        now = Time.now
+        return if certificate.not_before <= now && now <= certificate.not_after
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError, "Certificate is invalid"
+      end
+
+      def validate_certificate_purpose(certificate, actual_level)
+        return unless %w[QUALIFIED QSCD].include?(actual_level)
+
+        certificate_policy_oids = extract_certificate_policy_oids(certificate)
+        if certificate_policy_oids.empty?
+          raise SmartIdRuby::Errors::UnprocessableResponseError,
+                "Certificate does not have certificate policy OIDs and is not a qualified Smart-ID authentication certificate"
+        end
+        return if (QUALIFIED_CERTIFICATE_POLICY_OIDS - certificate_policy_oids).empty?
+
+        raise SmartIdRuby::Errors::UnprocessableResponseError,
+              "Certificate is not a qualified Smart-ID authentication certificate"
+      end
+
+      def extract_certificate_policy_oids(certificate)
+        extension = certificate.extensions.find { |ext| ext.oid == "certificatePolicies" }
+        return [] unless extension
+
+        extension.value.scan(/\b\d+(?:\.\d+)+\b/)
+      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