Class: EeIdVerification::AuthenticationResult

Inherits:
Object
  • Object
show all
Defined in:
lib/ee_id_verification/models.rb

Overview

Authentication result model containing the outcome of Estonian ID card authentication.

This class encapsulates all information returned from a completed (or failed) authentication attempt. It provides a comprehensive view of the authentication outcome including:

  • Authentication status and success/failure indicators
  • Personal information extracted from the ID card certificate
  • Error information if authentication failed
  • Convenient methods for checking authentication state

The result object serves as the primary interface between the authentication system and consuming applications, providing all necessary information to make authorization decisions and display user information.

Personal data fields match those available in Estonian ID card certificates:

  • personal_code: 11-digit Estonian personal identification code
  • given_name: User's first/given name(s)
  • surname: User's family/last name
  • country: Country code (always "EE" for Estonian cards)

Examples:

Successful authentication result

result = AuthenticationResult.new(
  session_id: "auth-123",
  status: :completed,
  authenticated: true,
  personal_code: "38001010008",
  given_name: "MARI",
  surname: "MAASIKAS",
  country: "EE"
)

if result.success?
  puts "Welcome, #{result.full_name}!"
  (result.personal_code)
end

Failed authentication result

result = AuthenticationResult.new(
  session_id: "auth-456",
  status: :failed,
  authenticated: false,
  error: "Invalid PIN1"
)

if result.failure?
  puts "Authentication failed: #{result.error}"
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes = {}) ⇒ AuthenticationResult

Initialize a new authentication result with the provided attributes.

Similar to AuthenticationSession, this uses flexible attribute assignment to allow setting result fields through a hash. The authenticated flag defaults to false to ensure secure defaults - authentication must be explicitly marked as successful.

Examples:

result = AuthenticationResult.new(
  authenticated: true,
  personal_code: "38001010008"
)

Parameters:

  • attributes (Hash) (defaults to: {}) —

    Result attributes to set

Options Hash (attributes):

  • :session_id (String) —

    Associated session ID

  • :status (Symbol) —

    Authentication status

  • :authenticated (Boolean) —

    Success flag

  • :error (String) —

    Error message for failures

  • :personal_code (String) —

    Estonian personal code

  • :given_name (String) —

    User's first name

  • :surname (String) —

    User's last name

  • :country (String) —

    Country code



191
192
193
194
195
196
197
198
199
200
 
# File 'lib/ee_id_verification/models.rb', line 191

def initialize(attributes = {})
  # Set provided attributes using dynamic attribute assignment
  attributes.each do |key, value|
    send("#{key}=", value) if respond_to?("#{key}=")
  end

  # Ensure authenticated defaults to false for security
  # Authentication must be explicitly set to true to be considered successful
  @authenticated ||= false
end

Instance Attribute Details

#authenticated ⇒ Boolean

Returns Whether authentication was successful.

Returns:

  • (Boolean) —

    Whether authentication was successful



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

#country ⇒ String?

Returns Country code from certificate (typically "EE").

Returns:

  • (String, nil) —

    Country code from certificate (typically "EE")



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

#error ⇒ String?

Returns Error message if authentication failed.

Returns:

  • (String, nil) —

    Error message if authentication failed



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

#given_name ⇒ String?

Returns User's first/given name from certificate.

Returns:

  • (String, nil) —

    User's first/given name from certificate



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

#personal_code ⇒ String?

Returns Estonian 11-digit personal identification code.

Returns:

  • (String, nil) —

    Estonian 11-digit personal identification code



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

#session_id ⇒ String

Returns ID of the session this result belongs to.

Returns:

  • (String) —

    ID of the session this result belongs to



167
168
169
 
# File 'lib/ee_id_verification/models.rb', line 167

def session_id
  @session_id
end

#status ⇒ Symbol

Returns Final authentication status (:completed, :failed, etc.).

Returns:

  • (Symbol) —

    Final authentication status (:completed, :failed, etc.)



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

#surname ⇒ String?

Returns User's family/last name from certificate.

Returns:

  • (String, nil) —

    User's family/last name from certificate



167
168
 
# File 'lib/ee_id_verification/models.rb', line 167

attr_accessor :session_id, :status, :authenticated, :error,
:personal_code, :given_name, :surname, :country

Instance Method Details

#authenticated? ⇒ Boolean

Check if the user was successfully authenticated.

This is the primary method for determining authentication success. It directly returns the authenticated flag which should only be true if PIN verification succeeded and personal data was extracted.

Returns:

  • (Boolean) —

    true if authentication was successful



209
210
211
 
# File 'lib/ee_id_verification/models.rb', line 209

def authenticated?
  @authenticated
end

#failure? ⇒ Boolean

Check if authentication failed or encountered an error.

This is the inverse of success? and provides a convenient way to check for any kind of authentication failure. Useful for error handling and conditional logic in authentication flows.

Returns:

  • (Boolean) —

    true if authentication failed or error occurred



238
239
240
 
# File 'lib/ee_id_verification/models.rb', line 238

def failure?
  !success?
end

#full_name ⇒ String?

Get the user's full name by combining given name and surname.

Estonian ID certificates store names in separate fields (given name and surname) following international X.509 certificate standards. This method provides a convenient way to get the complete name for display purposes.

The method handles various edge cases:

  • Missing given name or surname (returns partial name)
  • Both names missing (returns nil)
  • Extra whitespace (cleaned up by join)

Examples:

result.given_name = "MARI"
result.surname = "MAASIKAS"
puts result.full_name  # => "MARI MAASIKAS"

result.given_name = nil
result.surname = "MAASIKAS"
puts result.full_name  # => "MAASIKAS"

Returns:

  • (String, nil) —

    Full name or nil if no name components available



262
263
264
265
266
267
268
269
 
# File 'lib/ee_id_verification/models.rb', line 262

def full_name
  # Return nil if neither name component is available
  return nil unless given_name || surname

  # Combine available name components, filtering out nil values
  # compact removes nil values, join combines with space
  [given_name, surname].compact.join(" ")
end

#success? ⇒ Boolean

Check if authentication was successful and no errors occurred.

This method provides a more comprehensive success check than authenticated? by also ensuring no error occurred during the process. This catches cases where authentication might be marked as successful but an error was encountered during personal data extraction.

Examples:

if result.success?
  grant_access(result.personal_code)
else
  show_error_message(result.error)
end

Returns:

  • (Boolean) —

    true if authenticated and no error present



227
228
229
 
# File 'lib/ee_id_verification/models.rb', line 227

def success?
  authenticated? && !error
end