smart-id-ruby-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b91db6fa6f6c9adfc7ba1bc61e178f26b203d3a87517986ebb7528810fa4b506
+  data.tar.gz: 13f4360d2baf919d80c2d471383a914befc0bc25faddddfd713dee5c9b14c215
+SHA512:
+  metadata.gz: 28df6c16e3c0d265de6f09f7b438e1b506dbbd03de0bfbd342a0516c1569019c640fe00a675ecb29515d3d5570984f67e9c929ad2f47c17568f390bf89495c3d
+  data.tar.gz: f9225bed6e6cfdf290fa1da005a62a158c06667afe787f21cee437a17d370e9d13ed1ad1e09a8008b9840a0074c256213127abea6bc1589b383cc4c7ef4df9cb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/ParameterLists:
+  Max: 6
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+## [Unreleased]
+
+- Implemented trust-chain certificate validation parity with `TrustedCaCertStore` and `CertificateValidator`, and wired chain validation into signature/certificate-choice/authentication certificate validation flows.
+- Added `AuthenticationIdentity`, `SignatureResponse`, and `CertificateChoiceResponse` models for validator outputs and added `CertificateLevelMismatchError`.
+- Added `AuthenticationIdentityMapper` parity behavior to map identity fields from certificate subject and derive date-of-birth with certificate-attribute-first + national-identity fallback logic.
+- Added focused specs for notification authentication/signature builders and client factory wiring.
+- Added focused specs for certificate-by-document-number builder and client factory wiring.
+- Added focused validator specs for notification-authentication, signature, and certificate-choice response validation flows.
+- Added runtime dependency on `base64` to avoid Ruby 3.4 default-gem warnings.
+
+## [0.1.0] - 2026-02-17
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sergei Tsõganov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,436 @@
+[![Tests](https://github.com/maricavor/smart-id-ruby-client/actions/workflows/main.yml/badge.svg)](https://github.com/maricavor/smart-id-ruby-client/actions/workflows/main.yml)
+[![codecov](https://codecov.io/github/maricavor/smart-id-ruby-client/graph/badge.svg?token=WNE2Q8YLM5)](https://codecov.io/github/maricavor/smart-id-ruby-client)
+[![License: MIT](https://img.shields.io/github/license/mashape/apistatus.svg)](https://opensource.org/licenses/MIT)
+
+# smart-id-ruby-client
+
+Ruby client gem for integrating [Smart-ID RP API v3.1](https://sk-eid.github.io/smart-id-documentation/index.html) into Ruby applications.
+
+This gem follows the same high-level flow model as the Smart-ID Java client:
+
+- start session (authentication / certificate choice / signature)
+- poll session status
+- validate final session response
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick setup](#quick-setup)
+- [Logging](#logging)
+- [Interactions](#interactions)
+- [Flows](#flows)
+  - [Notification authentication](#notification-authentication)
+  - [Device-link authentication](#device-link-authentication)
+  - [Notification signature](#notification-signature)
+  - [Device-link signature](#device-link-signature)
+  - [Certificate by document number](#certificate-by-document-number)
+  - [Device-link certificate choice + linked notification signature](#device-link-certificate-choice--linked-notification-signature)
+  - [Notification certificate choice](#notification-certificate-choice)
+- [Generating device link and QR-code](#generating-device-link-and-qr-code)
+- [Session status polling](#session-status-polling)
+- [Response validation](#response-validation)
+- [Network and SSL configuration](#network-and-ssl-configuration)
+- [Exception handling](#exception-handling)
+- [Development](#development)
+- [License](#license)
+
+## Requirements
+
+- Ruby `>= 3.0`
+
+## Installation
+
+Add to your app:
+
+```bash
+bundle add smart-id-ruby-client
+```
+
+Or install directly:
+
+```bash
+gem install smart-id-ruby-client
+```
+
+## Quick setup
+
+```ruby
+require "smart-id-ruby-client" # or: require "smart_id_ruby"
+require "base64"
+require "securerandom"
+
+SmartIdRuby.configure do |config|
+  config.relying_party_uuid = ENV.fetch("SMART_ID_RP_UUID")
+  config.relying_party_name = ENV.fetch("SMART_ID_RP_NAME")
+  config.host_url = ENV.fetch("SMART_ID_HOST_URL") # e.g. https://sid.demo.sk.ee/smart-id-rp/v3/
+  config.default_certificate_level = "QUALIFIED" # optional app-level default
+  config.poller_timeout_seconds = 10             # optional
+end
+
+client = SmartIdRuby.client
+```
+
+## Logging
+
+The library uses `SmartIdRuby.logger` for connector-level logs.
+Default level is `WARN`.
+
+```ruby
+require "logger"
+require "smart-id-ruby-client" # or: require "smart_id_ruby"
+
+SmartIdRuby.logger = Logger.new($stdout)
+SmartIdRuby.logger.level = Logger::DEBUG
+```
+
+At `DEBUG`, logs include method, URL, and status code.
+Request and response bodies are not logged by default.
+
+## Interactions
+
+You can pass interactions either as hashes or helper objects.
+
+### Hash style
+
+```ruby
+[
+  { type: "displayTextAndPIN", displayText60: "Log in" },
+  { type: "confirmationMessage", displayText200: "Confirm login" }
+]
+```
+
+### Helper style (`NotificationInteraction`)
+
+```ruby
+[
+  SmartIdRuby::NotificationInteraction.confirmationMessageAndVerificationCodeChoice("Confirm login"),
+  SmartIdRuby::NotificationInteraction.confirmationMessage("Confirm login fallback"),
+  SmartIdRuby::NotificationInteraction.displayTextAndPin("Log in fallback")
+]
+```
+
+Ruby-style aliases are also available:
+
+- `display_text_and_pin`
+- `confirmation_message`
+- `confirmation_message_and_verification_code_choice`
+
+## Flows
+
+### Notification authentication
+
+```ruby
+rp_challenge = Base64.strict_encode64(SecureRandom.random_bytes(32))
+
+auth_builder = client.create_notification_authentication
+  .with_document_number("PNOEE-30303039914") # or .with_semantics_identifier("PNOEE-...")
+  .with_certificate_level("QUALIFIED")
+  .with_rp_challenge(rp_challenge)
+  .with_interactions([
+    SmartIdRuby::NotificationInteraction.displayTextAndPin("Log in")
+  ])
+  .with_share_md_client_ip_address(true) # optional
+
+auth_init = auth_builder.init_authentication_session
+session_id = auth_init["sessionID"] || auth_init[:sessionID]
+```
+
+### Device-link authentication
+
+```ruby
+rp_challenge = Base64.strict_encode64(SecureRandom.random_bytes(32))
+
+builder = client.create_device_link_authentication
+  .with_rp_challenge(rp_challenge)
+  .with_interactions([
+    SmartIdRuby::NotificationInteraction.confirmationMessage("Log in to MyApp")
+  ])
+  .with_initial_callback_url("https://example.com/callback") # optional
+
+# Anonymous device-link auth (no identifier)
+init = builder.init_authentication_session
+
+# Identified flow variants:
+# builder.with_document_number("PNOLT-40504040001-MOCK-Q")
+# builder.with_semantics_identifier("PNOEE-30303039914")
+```
+
+### Notification signature
+
+```ruby
+sig_builder = client.create_notification_signature
+  .with_semantics_identifier("PNOEE-30303039914") # or .with_document_number(...)
+  .with_certificate_level("QUALIFIED")
+  .with_signable_data("data to sign")
+  .with_interactions([
+    SmartIdRuby::NotificationInteraction.displayTextAndPin("Please sign")
+  ])
+  .with_nonce(SecureRandom.hex(8)) # optional
+
+sig_init = sig_builder.init_signature_session
+session_id = sig_init["sessionID"] || sig_init[:sessionID]
+```
+
+You can use `with_signable_hash(...)` instead of `with_signable_data(...)`.
+
+### Device-link signature
+
+```ruby
+sig_builder = client.create_device_link_signature
+  .with_document_number("PNOLT-40504040001-MOCK-Q") # or .with_semantics_identifier(...)
+  .with_certificate_level("QUALIFIED")
+  .with_signable_data("data to sign")
+  .with_interactions([
+    SmartIdRuby::NotificationInteraction.confirmationMessage("Please sign document")
+  ])
+  .with_initial_callback_url("https://example.com/callback") # optional
+
+sig_init = sig_builder.init_signature_session
+```
+
+### Certificate by document number
+
+```ruby
+result = client.create_certificate_by_document_number
+  .with_document_number("PNOLT-40504040001-MOCK-Q")
+  .with_certificate_level("QUALIFIED")
+  .get_certificate_by_document_number
+
+certificate_level = result[:certificate_level]
+certificate = result[:certificate] # OpenSSL::X509::Certificate
+```
+
+### Device-link certificate choice + linked notification signature
+
+```ruby
+cert_choice_init = client.create_device_link_certificate_request
+  .with_certificate_level("QUALIFIED")
+  .with_nonce(SecureRandom.hex(8))
+  .init_certificate_choice
+
+cert_choice_session_id = cert_choice_init["sessionID"] || cert_choice_init[:sessionID]
+
+cert_choice_status = client.session_status_poller.fetch_final_session_status(cert_choice_session_id)
+
+cert_choice_response = SmartIdRuby::Validation::CertificateChoiceResponseValidator.new
+  .validate(cert_choice_status, "QUALIFIED")
+
+linked_sig_init = client.create_linked_notification_signature
+  .with_document_number(cert_choice_response.document_number)
+  .with_linked_session_id(cert_choice_session_id)
+  .with_signable_data("data to sign")
+  .with_interactions([
+    SmartIdRuby::NotificationInteraction.displayTextAndPin("Please sign")
+  ])
+  .init_signature_session
+```
+
+### Notification certificate choice
+
+```ruby
+init = client.create_notification_certificate_choice
+  .with_semantics_identifier("PNOEE-30303039914")
+  .with_certificate_level("QUALIFIED")
+  .with_nonce(SecureRandom.hex(8))
+  .init_certificate_choice
+
+session_id = init["sessionID"] || init[:sessionID]
+```
+
+## Generating device link and QR-code
+
+After starting a device-link flow (authentication, signature, or certificate choice),
+you can create a signed device-link URI and QR image.
+
+```ruby
+# Example: after device-link authentication init
+auth_builder = client.create_device_link_authentication
+  .with_rp_challenge(Base64.strict_encode64(SecureRandom.random_bytes(32)))
+  .with_interactions([SmartIdRuby::NotificationInteraction.displayTextAndPin("Log in")])
+  .with_document_number("PNOLT-40504040001-MOCK-Q")
+
+init = auth_builder.init_authentication_session
+
+session_token = init["sessionToken"] || init[:sessionToken]
+session_secret = init["sessionSecret"] || init[:sessionSecret]
+device_link_base = init["deviceLinkBase"] || init[:deviceLinkBase]
+request = auth_builder.get_authentication_session_request
+request_interactions = request[:interactions]
+request_digest = request.dig(:signatureProtocolParameters, :rpChallenge)
+```
+
+Build unprotected and protected device-link:
+
+```ruby
+dynamic = client.create_dynamic_content
+  .with_device_link_base(device_link_base)
+  .with_session_type(SmartIdRuby::SessionType::AUTHENTICATION)
+  .with_device_link_type(SmartIdRuby::DeviceLinkType::QR_CODE)
+  .with_session_token(session_token)
+  .with_elapsed_seconds(1)
+  .with_lang("eng")
+  .with_digest(request_digest)
+  .with_interactions(request_interactions)
+
+unprotected_uri = dynamic.create_unprotected_uri
+device_link_uri = dynamic.build_device_link(session_secret)
+```
+
+Generate QR-code (PNG Data URI by default):
+
+```ruby
+qr_data_uri = SmartIdRuby::QrCodeGenerator.generate_data_uri(device_link_uri.to_s)
+
+# or create image object and convert manually
+image = SmartIdRuby::QrCodeGenerator.generate_image(device_link_uri.to_s, 610, 610, 4)
+qr_data_uri = SmartIdRuby::QrCodeGenerator.convert_to_data_uri(image, "png")
+```
+
+## Session status polling
+
+Use `SessionStatusPoller` for both one-shot and final-status polling.
+
+```ruby
+poller = client.session_status_poller
+
+# Query once
+status = poller.get_session_status(session_id)
+
+# Poll until COMPLETE
+final_status = poller.fetch_final_session_status(session_id)
+```
+
+Tune polling behavior:
+
+```ruby
+client.set_session_status_response_socket_open_time(:seconds, 5) # timeoutMs for each status request
+client.set_polling_sleep_timeout(:seconds, 1)                    # sleep between polls
+```
+
+Supported time units are `:milliseconds`, `:seconds`, `:minutes`, `:hours`.
+
+## Response validation
+
+Builders validate request/initialization responses.  
+For final session status payloads, use validators:
+
+### Notification authentication response validator
+
+```ruby
+identity = SmartIdRuby::Validation::NotificationAuthenticationResponseValidator.new
+  .validate(
+    final_status,
+    auth_builder.get_authentication_session_request,
+    "SMART_ID", # schema_name
+    nil         # brokered_rp_name (optional)
+  )
+```
+
+### Device-link authentication response validator
+
+```ruby
+response = SmartIdRuby::Validation::DeviceLinkAuthenticationResponseValidator.new.validate(
+  final_status,
+  auth_builder.get_authentication_session_request,
+  nil,        # user_challenge_verifier (required for Web2App/App2App)
+  "SMART_ID", # schema_name
+  nil         # brokered_rp_name
+)
+```
+
+### Signature response validator
+
+```ruby
+signature = SmartIdRuby::Validation::SignatureResponseValidator.new
+  .validate(final_status, "QUALIFIED")
+```
+
+### Certificate choice response validator
+
+```ruby
+choice = SmartIdRuby::Validation::CertificateChoiceResponseValidator.new
+  .validate(final_status, "QUALIFIED")
+```
+
+## Network and SSL configuration
+
+### Faraday request options
+
+```ruby
+client.network_connection_config = {
+  open_timeout: 5,
+  timeout: 30,
+  headers: { "X-Request-ID" => "123" }
+}
+```
+
+You can also nest options under `:request`:
+
+```ruby
+client.network_connection_config = {
+  request: {
+    open_timeout: 5,
+    timeout: 30
+  }
+}
+```
+
+### Custom Faraday connection
+
+```ruby
+client.configured_connection = Faraday.new(url: client.host_url) do |f|
+  f.adapter Faraday.default_adapter
+end
+```
+
+### Trusting custom CA certificates
+
+```ruby
+cert_store = OpenSSL::X509::Store.new
+cert_store.set_default_paths
+# cert_store.add_cert(OpenSSL::X509::Certificate.new(File.read("ca.pem")))
+
+ssl_context = OpenSSL::SSL::SSLContext.new
+ssl_context.cert_store = cert_store
+
+client.trust_ssl_context = ssl_context
+```
+
+## Exception handling
+
+Main exception classes:
+
+- `SmartIdRuby::Errors::RequestSetupError`
+- `SmartIdRuby::Errors::RequestValidationError`
+- `SmartIdRuby::Errors::UnprocessableResponseError`
+- `SmartIdRuby::Errors::SessionEndResultError`
+- `SmartIdRuby::Errors::SessionNotCompleteError`
+- `SmartIdRuby::Errors::CertificateLevelMismatchError`
+- `SmartIdRuby::Errors::DocumentUnusableError`
+- `SmartIdRuby::Errors::UserRefusedDisplayTextAndPinError`
+- `SmartIdRuby::Errors::UserRefusedConfirmationMessageError`
+- `SmartIdRuby::Errors::UserRefusedConfirmationMessageWithVerificationChoiceError`
+
+Connector/network-related classes:
+
+- `SmartIdRuby::Errors::SessionNotFoundError`
+- `SmartIdRuby::Errors::UserAccountNotFoundError`
+- `SmartIdRuby::Errors::RelyingPartyAccountConfigurationError`
+- `SmartIdRuby::Errors::NoSuitableAccountOfRequestedTypeFoundError`
+- `SmartIdRuby::Errors::PersonShouldViewSmartIdPortalError`
+- `SmartIdRuby::Errors::UnsupportedClientApiVersionError`
+- `SmartIdRuby::Errors::ServerMaintenanceError`
+
+## Development
+
+After checking out the repo:
+
+```bash
+bin/setup
+bundle exec rake
+```
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/smart-id-ruby-client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "smart_id_ruby"

data/lib/smart_id_ruby/callback_url.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SmartIdRuby
+  # Represents a Smart-ID callback URL and its associated one-time token
+  # generated by the Smart-ID service for Web2App/device-link flows.
+  class CallbackUrl
+    attr_reader :url, :token
+
+    def initialize(url:, token:)
+      @url = url
+      @token = token
+    end
+
+    def to_s
+      url
+    end
+  end
+end