smart-id-ruby-client 0.1.0

data/lib/smart_id_ruby/callback_url_util.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "securerandom"
+require "uri"
+
+module SmartIdRuby
+  # Utility helpers for creating and validating Smart-ID callback URLs and their tokens.
+  class CallbackUrlUtil
+    class << self
+      def create_callback_url(base_url)
+        raise SmartIdRuby::Errors::RequestSetupError, "Parameter for 'baseUrl' cannot be empty" if blank?(base_url)
+
+        url_token = SecureRandom.urlsafe_base64(32, false)
+        uri = URI.parse(base_url.to_s)
+        query = URI.decode_www_form(uri.query.to_s)
+        query << ["value", url_token]
+        uri.query = URI.encode_www_form(query)
+        SmartIdRuby::CallbackUrl.new(url: uri.to_s, token: url_token)
+      end
+
+      def validate_session_secret_digest(session_secret_digest, session_secret)
+        if blank?(session_secret_digest)
+          raise SmartIdRuby::Errors::RequestSetupError, "Parameter for 'sessionSecretDigest' cannot be empty"
+        end
+        if blank?(session_secret)
+          raise SmartIdRuby::Errors::RequestSetupError, "Parameter for 'sessionSecret' cannot be empty"
+        end
+
+        calculated_session_secret_digest = calculate_digest(session_secret)
+        return if session_secret_digest.to_s == calculated_session_secret_digest
+
+        raise SmartIdRuby::Errors::SessionSecretMismatchError,
+              "Session secret digest from callback does not match calculated session secret digest"
+      end
+
+      private
+
+      def calculate_digest(session_secret)
+        decoded_session_secret = Base64.strict_decode64(session_secret)
+        digest = OpenSSL::Digest::SHA256.digest(decoded_session_secret)
+        Base64.urlsafe_encode64(digest, padding: false)
+      rescue ArgumentError => e
+        raise SmartIdRuby::Errors::RequestSetupError,
+              "Parameter 'sessionSecret' is not Base64-encoded value: #{e.message}"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/smart_id_ruby/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  # Main entry point for using Smart-ID services.
+  class Client
+    attr_accessor :relying_party_uuid, :relying_party_name, :host_url,
+                  :network_connection_config, :configured_connection
+
+    def initialize
+      @polling_sleep_timeout = 1
+      @polling_sleep_time_unit = :seconds
+      @session_status_response_socket_open_time = nil
+      @smart_id_connector = nil
+      @session_status_poller = nil
+      @ssl_context = nil
+    end
+
+    def create_device_link_certificate_request
+      Flows::DeviceLinkCertificateChoiceSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_linked_notification_signature
+      Flows::LinkedNotificationSignatureSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_notification_certificate_choice
+      Flows::NotificationCertificateChoiceSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_device_link_authentication
+      Flows::DeviceLinkAuthenticationSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_notification_authentication
+      Flows::NotificationAuthenticationSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_device_link_signature
+      Flows::DeviceLinkSignatureSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_certificate_by_document_number
+      Flows::CertificateByDocumentNumberRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def create_notification_signature
+      Flows::NotificationSignatureSessionRequestBuilder.new(smart_id_connector)
+        .with_relying_party_uuid(relying_party_uuid)
+        .with_relying_party_name(relying_party_name)
+    end
+
+    def session_status_poller
+      @session_status_poller ||= begin
+        poller = Rest::SessionStatusPoller.new(smart_id_connector)
+        poller.set_polling_sleep_time(@polling_sleep_time_unit, @polling_sleep_timeout)
+        poller
+      end
+    end
+
+    def create_dynamic_content
+      DeviceLinkBuilder.new.with_relying_party_name(relying_party_name)
+    end
+
+    def set_polling_sleep_timeout(unit, timeout)
+      @polling_sleep_time_unit = unit
+      @polling_sleep_timeout = timeout
+      return unless @session_status_poller
+
+      @session_status_poller.set_polling_sleep_time(unit, timeout)
+    end
+
+    def set_session_status_response_socket_open_time(unit, value)
+      @session_status_response_socket_open_time = { unit: unit, value: value }
+      return unless @smart_id_connector
+
+      @smart_id_connector.set_session_status_response_socket_open_time(unit, value)
+    end
+
+    def trust_ssl_context=(ssl_context)
+      @ssl_context = ssl_context
+      @smart_id_connector = nil
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def smart_id_connector
+      if host_url.nil? || host_url.to_s.strip.empty?
+        raise SmartIdRuby::Errors::RequestSetupError, "Value for 'host_url' cannot be empty"
+      end
+
+      @smart_id_connector ||= begin
+        connector = Rest::Connector.new(
+          host_url: host_url,
+          configured_connection: configured_connection,
+          network_connection_config: network_connection_config,
+          ssl_context: @ssl_context
+        )
+
+        if @session_status_response_socket_open_time
+          connector.set_session_status_response_socket_open_time(
+            @session_status_response_socket_open_time[:unit],
+            @session_status_response_socket_open_time[:value]
+          )
+        end
+
+        connector
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/smart_id_ruby/configuration.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+# rubocop:disable Style/RescueModifier
+module SmartIdRuby
+  # Mixin that provides global configuration for the Smart-ID Ruby client
+  # (e.g. relying party UUID/name, host URL, and network options).
+  module Configuration
+    DEFAULT_CONFIG = {
+      relying_party_uuid: nil,
+      relying_party_name: nil,
+      host_url: nil,
+      default_certificate_level: "ADVANCED",
+      poller_timeout_seconds: 10,
+      truststore_path: nil,
+      truststore_type: nil,
+      truststore_password: nil,
+      tls_config: nil,
+      network_connection_config: nil,
+      configured_connection: nil
+    }.freeze
+
+    def configuration
+      @configuration ||= OpenStruct.new(DEFAULT_CONFIG)
+    end
+
+    def configure
+      yield(configuration)
+      reload_config
+    end
+
+    def client
+      @client ||= build_client(configuration)
+    end
+
+    def reset_client!
+      @client = nil
+    end
+
+    def reload_config
+      reset_client!
+      true
+    end
+
+    private
+
+    def build_client(config)
+      client = SmartIdRuby::Client.new
+      client.relying_party_uuid = config.relying_party_uuid
+      client.relying_party_name = config.relying_party_name
+      client.host_url = config.host_url
+      client.network_connection_config = config.network_connection_config
+      client.configured_connection = config.configured_connection
+
+      if config.poller_timeout_seconds
+        client.set_session_status_response_socket_open_time(:seconds, config.poller_timeout_seconds.to_i)
+      end
+
+      ssl_context = build_ssl_context(config)
+      client.trust_ssl_context = ssl_context if ssl_context
+
+      client
+    end
+
+    def build_ssl_context(config)
+      path = config.truststore_path
+      return nil if path.nil? || path.to_s.strip.empty?
+
+      truststore_type = normalize_truststore_type(config.truststore_type, path)
+      validate_truststore_configuration!(truststore_type, path, config.truststore_password)
+
+      cert_store = OpenSSL::X509::Store.new
+      cert_store.set_default_paths
+
+      if truststore_type == :pkcs12
+        add_pkcs12_certificates(cert_store, path, config.truststore_password)
+      else
+        validate_truststore_file!(path)
+        cert_store.add_file(path)
+      end
+
+      ssl_context = OpenSSL::SSL::SSLContext.new
+      ssl_context.cert_store = cert_store
+      ssl_context
+    rescue Errno::ENOENT, OpenSSL::X509::StoreError, OpenSSL::PKCS12::PKCS12Error => e
+      log_debug("[SmartIdRuby] Truststore diagnostics for path=#{path}: #{truststore_diagnostics(path)}") rescue nil
+      raise SmartIdRuby::Error,
+            "Failed to load #{truststore_type || "truststore"} from '#{path}': #{e.message}"
+    end
+
+    def normalize_truststore_type(value, path)
+      normalized = value.to_s.strip.upcase
+      if normalized.empty?
+        return path.to_s.downcase.end_with?(".p12", ".pfx") ? :pkcs12 : :pem
+      end
+
+      return :pem if normalized == "PEM"
+      return :pkcs12 if %w[PKCS12 P12].include?(normalized)
+
+      raise SmartIdRuby::Error, "Unsupported truststore_type '#{value}'. Supported types: PEM, PKCS12, P12"
+    end
+
+    def add_pkcs12_certificates(cert_store, path, password)
+      validate_truststore_configuration!(:pkcs12, path, password)
+      validate_truststore_file!(path)
+
+      pkcs12 = OpenSSL::PKCS12.new(File.binread(path), password)
+      certificates = [pkcs12.certificate, *Array(pkcs12.ca_certs)].compact
+      raise SmartIdRuby::Error, "PKCS12 truststore does not contain any certificates" if certificates.empty?
+
+      certificates.each { |certificate| cert_store.add_cert(certificate) }
+    end
+
+    def validate_truststore_configuration!(truststore_type, path, truststore_password)
+      return if path.nil? || path.to_s.strip.empty?
+
+      if truststore_type == :pkcs12 && truststore_password.to_s.empty?
+        log_debug("[SmartIdRuby] PKCS12 truststore password missing/empty. path=#{path}") rescue nil
+        raise SmartIdRuby::Error,
+              "PKCS12 truststore password is missing/empty for '#{path}'"
+      end
+    end
+
+    def validate_truststore_file!(path)
+      return if path.nil? || path.to_s.strip.empty?
+
+      unless File.exist?(path)
+        log_debug("[SmartIdRuby] Truststore file missing. path=#{path} diag=#{truststore_diagnostics(path)}") rescue nil
+        raise SmartIdRuby::Error,
+              "Truststore file does not exist at '#{path}'"
+      end
+
+      return if File.file?(path)
+
+      log_debug("[SmartIdRuby] Truststore path is not a regular file. path=#{path} diag=#{truststore_diagnostics(path)}") rescue nil
+      raise SmartIdRuby::Error,
+            "Truststore path is not a regular file at '#{path}'"
+    end
+
+    def truststore_diagnostics(path)
+      return "path=nil" if path.nil?
+
+      dir = File.dirname(path) rescue nil
+      basename = File.basename(path) rescue nil
+
+      exists = File.exist?(path)
+      readable = exists ? File.readable?(path) : false
+      stat = File.stat(path) rescue nil
+      size = stat&.size
+      mode = stat&.mode
+
+      entries =
+        if dir && Dir.exist?(dir)
+          begin
+            Dir.entries(dir).sort.first(30)
+          rescue StandardError
+            []
+          end
+        else
+          []
+        end
+
+      {
+        exists: exists,
+        readable: readable,
+        size_bytes: size,
+        mode: mode,
+        dir: dir,
+        basename: basename,
+        dir_entries_sample: entries
+      }.to_s
+    end
+
+    def log_debug(message)
+      # Use the gem logger (defined in `smart_id_ruby.rb`) so logging behavior is consistent.
+      # Note: the logger level may be WARN by default when not running under Rails.
+      SmartIdRuby.logger.debug(message)
+    rescue StandardError
+      warn(message)
+    end
+  end
+end
+# rubocop:enable Style/RescueModifier

data/lib/smart_id_ruby/device_link_builder.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "uri"
+
+module SmartIdRuby
+  module DeviceLinkType
+    QR_CODE = "QR"
+    WEB_2_APP = "Web2App"
+    APP_2_APP = "App2App"
+  end
+
+  module SessionType
+    AUTHENTICATION = "auth"
+    SIGNATURE = "sign"
+    CERTIFICATE_CHOICE = "cert"
+  end
+
+  # Builder for creating Smart-ID device-link URIs and auth codes.
+  class DeviceLinkBuilder
+    ALLOWED_VERSION = "1.0"
+    DEFAULT_SCHEME_NAME = "smart-id"
+    DEFAULT_LANGUAGE = "eng"
+    SUPPORTED_DEVICE_LINK_TYPES = [
+      DeviceLinkType::QR_CODE,
+      DeviceLinkType::WEB_2_APP,
+      DeviceLinkType::APP_2_APP
+    ].freeze
+    SUPPORTED_SESSION_TYPES = [
+      SessionType::AUTHENTICATION,
+      SessionType::SIGNATURE,
+      SessionType::CERTIFICATE_CHOICE
+    ].freeze
+
+    def initialize
+      @scheme_name = DEFAULT_SCHEME_NAME
+      @version = ALLOWED_VERSION
+      @lang = DEFAULT_LANGUAGE
+      @device_link_base = nil
+      @device_link_type = nil
+      @session_type = nil
+      @session_token = nil
+      @elapsed_seconds = nil
+      @digest = nil
+      @relying_party_name_base64 = nil
+      @brokered_rp_name_base64 = nil
+      @interactions = nil
+      @initial_callback_url = nil
+    end
+
+    def with_scheme_name(value)
+      @scheme_name = value
+      self
+    end
+
+    def with_device_link_base(value)
+      @device_link_base = value
+      self
+    end
+
+    def with_version(value)
+      @version = value
+      self
+    end
+
+    def with_device_link_type(value)
+      @device_link_type = normalize_device_link_type(value)
+      self
+    end
+
+    def with_session_type(value)
+      @session_type = normalize_session_type(value)
+      self
+    end
+
+    def with_session_token(value)
+      @session_token = value
+      self
+    end
+
+    def with_elapsed_seconds(value)
+      @elapsed_seconds = value
+      self
+    end
+
+    def with_lang(value)
+      @lang = value
+      self
+    end
+
+    def with_digest(value)
+      @digest = value
+      self
+    end
+
+    def with_relying_party_name(value)
+      @relying_party_name_base64 = Base64.strict_encode64(value.to_s.dup.force_encoding("UTF-8"))
+      self
+    end
+
+    def with_brokered_rp_name(value)
+      @brokered_rp_name_base64 = Base64.strict_encode64(value.to_s.dup.force_encoding("UTF-8"))
+      self
+    end
+
+    def with_interactions(value)
+      @interactions = encode_interactions(value)
+      self
+    end
+
+    def with_initial_callback_url(value)
+      @initial_callback_url = value
+      self
+    end
+
+    def create_unprotected_uri
+      validate_input_parameters!
+
+      query_params = [
+        ["deviceLinkType", @device_link_type]
+      ]
+      query_params << ["elapsedSeconds", @elapsed_seconds.to_s] unless @elapsed_seconds.nil?
+      query_params.concat(
+        [
+          ["sessionToken", @session_token],
+          ["sessionType", @session_type],
+          ["version", @version],
+          ["lang", @lang]
+        ]
+      )
+
+      uri = append_query_params(@device_link_base, query_params)
+      logger.debug("Created unprotected device link URI=#{sanitize_uri(uri)}")
+      uri
+    end
+
+    def build_device_link(session_secret)
+      unprotected_uri = create_unprotected_uri
+      logger.debug("Building protected device link with scheme=#{@scheme_name}, session_type=#{@session_type}, device_link_type=#{@device_link_type}")
+      auth_code = generate_auth_code(unprotected_uri.to_s, session_secret)
+      uri = append_query_params(unprotected_uri.to_s, [["authCode", auth_code]])
+      logger.debug("Built protected device link URI=#{sanitize_uri(uri)}")
+      uri
+    end
+
+    private
+
+    def validate_input_parameters!
+      raise_request_setup_error("Parameter 'deviceLinkBase' cannot be empty") if blank?(@device_link_base)
+      raise_request_setup_error("Parameter 'version' cannot be empty") if blank?(@version)
+      raise_request_setup_error("Only version 1.0 is allowed") unless @version == ALLOWED_VERSION
+      raise_request_setup_error("Parameter 'deviceLinkType' must be set") if blank?(@device_link_type)
+      raise_request_setup_error("Parameter 'sessionType' must be set") if blank?(@session_type)
+      raise_request_setup_error("Parameter 'sessionToken' cannot be empty") if blank?(@session_token)
+      raise_request_setup_error("Parameter 'lang' must be set") if blank?(@lang)
+
+      if @device_link_type == DeviceLinkType::QR_CODE && @elapsed_seconds.nil?
+        raise_request_setup_error("Parameter 'elapsedSeconds' must be set when 'deviceLinkType' is QR_CODE")
+      end
+      if @device_link_type != DeviceLinkType::QR_CODE && !@elapsed_seconds.nil?
+        raise_request_setup_error("Parameter 'elapsedSeconds' should only be used when 'deviceLinkType' is QR_CODE")
+      end
+    end
+
+    def validate_auth_code_params!
+      raise_request_setup_error("Parameter 'schemeName' cannot be empty") if blank?(@scheme_name)
+      raise_request_setup_error("Parameter 'relyingPartyName' cannot be empty") if blank?(@relying_party_name_base64)
+
+      has_callback = !blank?(@initial_callback_url)
+      if @device_link_type == DeviceLinkType::QR_CODE && has_callback
+        raise_request_setup_error("Parameter 'initialCallbackUrl' must be empty when 'deviceLinkType' is QR_CODE")
+      end
+      if [DeviceLinkType::APP_2_APP, DeviceLinkType::WEB_2_APP].include?(@device_link_type) && !has_callback
+        raise_request_setup_error("Parameter 'initialCallbackUrl' must be provided when 'deviceLinkType' is APP_2_APP or WEB_2_APP")
+      end
+
+      if [SessionType::AUTHENTICATION, SessionType::SIGNATURE].include?(@session_type)
+        raise_request_setup_error("Parameter 'digest' must be set when 'sessionType' is AUTHENTICATION or SIGNATURE") if blank?(@digest)
+        raise_request_setup_error("Parameter 'interactions' must be set when 'sessionType' is AUTHENTICATION or SIGNATURE") if blank?(@interactions)
+      end
+
+      if @session_type == SessionType::CERTIFICATE_CHOICE
+        raise_request_setup_error("Parameter 'digest' must be empty when 'sessionType' is CERTIFICATE_CHOICE") unless blank?(@digest)
+        raise_request_setup_error("Parameter 'interactions' must be empty when 'sessionType' is CERTIFICATE_CHOICE") unless blank?(@interactions)
+      end
+    end
+
+    def generate_auth_code(unprotected_link, session_secret_base64)
+      raise_request_setup_error("Parameter 'sessionSecret' cannot be empty") if blank?(session_secret_base64)
+
+      validate_auth_code_params!
+
+      payload = [
+        @scheme_name,
+        signature_protocol_for_session,
+        or_empty(@digest),
+        @relying_party_name_base64,
+        or_empty(@brokered_rp_name_base64),
+        or_empty(@interactions),
+        or_empty(@initial_callback_url),
+        unprotected_link
+      ].join("|")
+      logger.debug("Generating authCode payload metadata scheme=#{@scheme_name},
+        protocol=#{signature_protocol_for_session}, has_digest=#{!blank?(@digest)},
+        has_interactions=#{!blank?(@interactions)}, has_callback=#{!blank?(@initial_callback_url)}")
+
+      session_secret = Base64.decode64(session_secret_base64)
+      hmac = OpenSSL::HMAC.digest(
+        "SHA256", session_secret, payload
+      )
+      Base64.urlsafe_encode64(hmac).sub(/=*$/, '')
+    rescue OpenSSL::HMACError, ArgumentError => e
+      raise SmartIdRuby::Errors::RequestSetupError, "Failed to calculate authCode: #{e.message}"
+    end
+
+    def signature_protocol_for_session
+      case @session_type
+      when SessionType::AUTHENTICATION then "ACSP_V2"
+      when SessionType::SIGNATURE then "RAW_DIGEST_SIGNATURE"
+      when SessionType::CERTIFICATE_CHOICE then ""
+      else ""
+      end
+    end
+
+    def append_query_params(base_url, new_params)
+      uri = URI.parse(base_url.to_s)
+      params = URI.decode_www_form(uri.query.to_s)
+      params.concat(new_params)
+      uri.query = URI.encode_www_form(params)
+      uri
+    end
+
+    def encode_interactions(value)
+      return nil if value.nil?
+      return value if value.is_a?(String)
+
+      interactions = Array(value).compact.map do |interaction|
+        if interaction.respond_to?(:to_h)
+          interaction.to_h
+        elsif interaction.is_a?(Hash)
+          interaction
+        else
+          raise_request_setup_error("Unsupported interaction object type: #{interaction.class}")
+        end
+      end
+
+      Base64.strict_encode64(JSON.generate(interactions))
+    end
+
+    def normalize_device_link_type(value)
+      return value if value.nil?
+
+      normalized = value.to_s
+      return normalized if SUPPORTED_DEVICE_LINK_TYPES.include?(normalized)
+
+      raise_request_setup_error("Unsupported device link type: #{value}")
+    end
+
+    def normalize_session_type(value)
+      return value if value.nil?
+
+      normalized = value.to_s
+      return normalized if SUPPORTED_SESSION_TYPES.include?(normalized)
+
+      raise_request_setup_error("Unsupported session type: #{value}")
+    end
+
+    def or_empty(value)
+      value.nil? ? "" : value
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def raise_request_setup_error(message)
+      raise SmartIdRuby::Errors::RequestSetupError, message
+    end
+
+    def logger
+      SmartIdRuby.logger
+    end
+
+    def sanitize_uri(uri)
+      parsed = URI.parse(uri.to_s)
+      query = URI.decode_www_form(parsed.query.to_s).map do |key, value|
+        [key, sensitive_param?(key) ? "[FILTERED]" : value]
+      end
+      parsed.query = URI.encode_www_form(query)
+      parsed.to_s
+    rescue StandardError
+      uri.to_s
+    end
+
+    def sensitive_param?(name)
+      %w[sessionToken authCode].include?(name.to_s)
+    end
+  end
+end