yoti 1.6.3 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296612e32508787e11d3c6f9404434b9d9575284008ae7d60df4a20f83526f6f
-  data.tar.gz: 4e0e6a0c0ea6a297399df4a9937ae3e6cd82da95f67d5a70b8cc7db0665e5c50
+  metadata.gz: 62813310617665f67200974ba737f52d7c9bd2c1b139657b5ec672253ab3d133
+  data.tar.gz: 474d9dff07562499e19ec35d261dadbc056dbe7818bf35620ba7247ea7169569
 SHA512:
-  metadata.gz: fc8a50eab70a1b29ba480e7df303144d56b4edb46b48124292dbfb98de9167659eee80b2d38e0c633c709151953252cb888dad5f2114c721eed8871915b3f0b2
-  data.tar.gz: 2c8dcc5342813067af5fb6980ef0acb8c5c8f2981c23fbf4311261a46034f852ba35b1c028a6cfed33c5fda52d0b193cb857e145cbafa4b342e0377e0ff2effb
+  metadata.gz: 5c9c3ddc325973e5da3598c289428f01ccb7964ef7faed15b56faa7d9067b5f34f20a2b3336e1b357fb388898810595ccdc1bc2b2665213c44513b9ef493cf90
+  data.tar.gz: eb86020139c4e892f289f70a5eb9dfa15b8f2daee955d67ff16a3d93e6eab57e2847eac54f57545b9430b6c6373185fdf485c6fe726831d63b24c5e982b4931c

data/README.md

@@ -1,44 +1,25 @@
 # Yoti Ruby SDK
 
 [![Build Status](https://travis-ci.com/getyoti/yoti-ruby-sdk.svg?branch=master)](https://travis-ci.com/getyoti/yoti-ruby-sdk)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=getyoti%3Aruby&metric=coverage)](https://sonarcloud.io/dashboard?id=getyoti%3Aruby)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=getyoti%3Aruby&metric=bugs)](https://sonarcloud.io/dashboard?id=getyoti%3Aruby)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=getyoti%3Aruby&metric=code_smells)](https://sonarcloud.io/dashboard?id=getyoti%3Aruby)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=getyoti%3Aruby&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=getyoti%3Aruby)
 
 Welcome to the Yoti Ruby SDK. This repository contains the tools you need to quickly integrate your Ruby back-end with Yoti so that your users can share their identity details with your application in a secure and trusted way.
 
 ## Table of Contents
 
-1. [An Architectural view](#an-architectural-view) - High level overview of integration
 1. [Requirements](#requirements) - Everything you need to get started
-1. [Installing the SDK](#installing-the-sdk) - How to install our SDK
-1. [Configuration](#configuration) - Configuring the SDK
-1. [Profile Retrieval](#profile-retrieval) - How to retrieve a Yoti profile using the one time use token
-1. [AML Integration](#aml-integration) - How to integrate with Yoti's AML (Anti Money Laundering) service
-1. [Running the Examples](#running-the-examples) - How to run the example projects provided
-1. [API Coverage](#api-coverage) - Attributes defined
-1. [Support](#support) - Please feel free to reach out
-
-## An Architectural view
-
-To integrate your application with Yoti, your back-end must expose a GET endpoint that Yoti will use to forward tokens.
-The endpoint is configured in the [Yoti Hub](https://hub.yoti.com) where you create/update your application. To see an example of how this is configured, see the [Running the Examples](#running-the-examples) section.
 
-The image below shows how your application back-end and Yoti integrate into the context of a Login flow.
-Yoti SDK carries out for you steps 6, 7, 8 and the profile decryption in step 9.
-
-![alt text](login_flow.png "Login flow")
-
-Yoti also allows you to enable user details verification from your mobile app by means of the Android (TBA) and iOS (TBA) SDKs. In that scenario, your Yoti-enabled mobile app is playing both the role of the browser and the Yoti app. Your back-end doesn't need to handle these cases in a significantly different way, but you might decide to handle the `User-Agent` header in order to provide different responses for desktop and mobile clients.
+1. [Installing the SDK](#installing-the-sdk) - How to install our SDK
 
-## References
+1. [Setup](#setup) - Setup required before using the Yoti services
 
-* [AES-256 symmetric encryption][]
-* [RSA pkcs asymmetric encryption][]
-* [Protocol buffers][]
-* [Base64 data][]
+1. [Products](#products) -
+Links to more information about the products offered by the Yoti SDK
 
-[AES-256 symmetric encryption]:   https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
-[RSA pkcs asymmetric encryption]: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
-[Protocol buffers]:               https://en.wikipedia.org/wiki/Protocol_Buffers
-[Base64 data]:                    https://en.wikipedia.org/wiki/Base64
+1. [Support](#support) - Please feel free to reach out
 
 ## Requirements
 
@@ -72,7 +53,7 @@ bundle install
 Or simply run the following command from your terminal:
 
 ```shell
-[sudo] gem install yoti
+gem install yoti
 ```
 
 ## SDK Project Import
@@ -85,7 +66,12 @@ rails generate yoti:install
 
 The generated initialisation file can be found in `config/initializers/yoti.rb`.
 
-## Configuration
+## Setup
+
+For each service you will need:
+
+* Your Client SDK ID, generated by [Yoti Hub](https://hub.yoti.com) when you create (and then publish) your app. 
+* Your .pem file. This is your own unique private key which your browser generates from the [Yoti Hub](https://hub.yoti.com) when you create an application.
 
 A minimal Yoti client initialisation looks like this:
 
@@ -97,10 +83,8 @@ end
 ```
 
 Make sure the following environment variables can be accessed by your app:
-
-`YOTI_CLIENT_SDK_ID` - found on the Key settings page on your Yoti Hub
-
-`YOTI_KEY_FILE_PATH` - the full path to your security key downloaded from the *Keys* settings page (e.g. /Users/developer/access-security.pem)
+- `YOTI_CLIENT_SDK_ID`
+- `YOTI_KEY_FILE_PATH`
 
 The following options are available:
 
@@ -140,197 +124,11 @@ heroku config:add YOTI_KEY ="$(cat your-access-security.pem)"
 
 [Heroku Command Line]: https://devcenter.heroku.com/articles/heroku-command-line
 
-## Profile Retrieval
-
-When your application receives a one time use token via the exposed endpoint (it will be assigned to a query string parameter named `token`), you can easily retrieve the user profile:
-
-```ruby
-one_time_use_token = params[:token]
-yoti_activity_details = Yoti::Client.get_activity_details(one_time_use_token)
-```
-
-Before you inspect the user profile, you might want to check whether the user validation was successful. This is done as follows:
-
-```ruby
-if yoti_activity_details.outcome == 'SUCCESS'
-  profile = yoti_activity_details.profile
-  given_names = profile.given_names.value
-  family_name = profile.family_name.value
-else
-  # handle unhappy path
-end
-```
-
-The `profile` object provides a set of attributes corresponding to user attributes. Whether the attributes are present or not depends on the settings you have applied to your app on Yoti Hub.
-
-### Handling Users
-
-When you retrieve the user profile, you receive a user ID generated by Yoti exclusively for your application.
-This means that if the same individual logs into another app, Yoti will assign her/him a different ID.
-You can use this ID to verify whether (for your application) the retrieved profile identifies a new or an existing user.
-Here is an example of how this works:
-
-```ruby
-if yoti_activity_details.outcome == 'SUCCESS'
-  user = your_user_search_function(yoti_activity_details.user_id)
-  profile = yoti_activity_details.profile
-
-  if user
-    # handle login
-    email = profile.email_address.value
-  else
-    # handle registration
-    given_names = profile.given_names.value
-    family_name = profile.family_name.value
-    email = profile.email_address.value
-  end
-else
-  # handle unhappy path
-end
-```
-
-Where `your_user_search_function` is a piece of logic in your app that is supposed to find a user, given a user_id. Regardless of whether the user is a new or an existing one, Yoti will always provide their profile, so you don't necessarily need to store it.
-
-You can retrieve the sources and verifiers for each attribute as follows:
-
-```ruby
-given_names_sources = profile.given_names.sources # list of anchors
-given_names_verifiers = profile.given_names.verifiers # list of anchors
-given_names_anchors = profile.given_names.anchors # list of anchors
-```
-You can also retrieve further properties from these respective anchors in the following way:
-
-```ruby
-# Retrieving properties of the first anchor
-type = given_names_sources[0].type # string
-value = given_names_sources[0].value # string
-sub_type = given_names_sources[0].sub_type # string
-time_stamp = given_names_sources[0].signed_time_stamp.time_stamp # DateTime object
-origin_server_certs = given_names_sources[0].origin_server_certs # list of X509 certificates
-```
-
-In case you want to prove the sources and verifiers of the helper`ActivityDetails.age_verified` on `Age Over 18` set as age derivation, please retrieve it's original attribute from the profile as follow:
-
-```ruby
-age_attribute = profile.get_attribute('age_over:18')
-sources = age_attribute.sources
-verifiers = age_attribute.verifiers
-anchors = age_attribute.anchors
-```
-
-## AML Integration
-
-Yoti provides an AML (Anti Money Laundering) check service to allow a deeper KYC process to prevent fraud. This is a chargeable service, so please contact [sdksupport@yoti.com](mailto:sdksupport@yoti.com) for more information.
-
-Yoti will provide a boolean result on the following checks:
-
-* PEP list - Verify against Politically Exposed Persons list
-* Fraud list - Verify against  US Social Security Administration Fraud (SSN Fraud) list
-* Watch list - Verify against watch lists from the Office of Foreign Assets Control
-
-To use this functionality you must ensure your application is assigned to your organisation in the Yoti Hub - please see [here](https://developers.yoti.com/yoti-app-integration/yoti-app-integration#step-1-creating-an-organisation) for further information.
-
-For the AML check you will need to provide the following:
-
-* Data provided by Yoti (please ensure you have selected the Given name(s) and Family name attributes for your scenario on the Yoti Hub)
-  * Given name(s)
-  * Family name
-* Data that must be collected from the user:
-  * Country of residence (must be an ISO 3166 3-letter code)
-  * Social Security Number (US citizens only)
-  * Postcode/Zip code (US citizens only)
-
-### Consent
-
-Performing an AML check on a person *requires* their consent.
-**You must ensure you have user consent *before* using this service.**
-
-### Code Example
-
-Given a YotiClient initialised with your SDK ID and KeyPair (see [Client Initialisation](#client-initialisation)) performing an AML check is a straightforward case of providing basic profile data.
-
-```ruby
-require 'yoti'
-
-Yoti.configure do |config|
-  config.client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
-  config.key_file_path = ENV['YOTI_KEY_FILE_PATH']
-end
-
-aml_address = Yoti::AmlAddress.new('GBR')
-aml_profile = Yoti::AmlProfile.new('Edward Richard George', 'Heath', aml_address)
-
-puts Yoti::Client.aml_check(aml_profile)
-```
+## Products
 
-## Running the Examples
-
-The examples can be found in the [examples folder](examples). 
-
-### Ruby on Rails
-
-1. Create your application in the [Yoti Hub](https://hub.yoti.com)
-1. Set the application domain of your app to `localhost:3001`
-1. Set the scenario callback URL to `/profile`
-1. Rename the [.env.example](examples/rails/.env.example) file to `.env` 
-1. Fill in the environment variables in this file with the ones specific to your application (mentioned in the [Configuration](#configuration) section)
-1. Install the dependencies by running the following commands
-    ```ruby
-    $ bundle install
-    $ gem install foreman # We are doing this as it's not recommended to include foreman in your Gemfile
-    ```
-1. Start the server `foreman start`
-
-Visiting `https://localhost:3001/` should show a Yoti Connect button
-
-### Sinatra
-
-1. Create your application in the [Yoti Hub](https://hub.yoti.com)
-1. Set the application domain of your app to `localhost:4567`
-1. Set the scenario callback URL to `/profile`
-1. Rename the [.env.example](examples/sinatra/.env.example) file to `.env`
-1. Fill in the environment variables in this file with the ones specific to your application (mentioned in the [Configuration](#configuration) section)
-1. Install the dependencies by running the following commands
-    ```ruby
-    $ bundle install
-    $ gem install foreman # We are doing this as it's not recommended to include foreman in your Gemfile
-    ```
-1. Start the server `foreman start`
-
-Visiting `https://localhost:4567/` should show a Yoti Connect button
-
-### AML Check
-
-* rename the [.env.example](examples/aml_check/.env.example) file to `.env` and fill in the required configuration values
-* install the dependencies with `bundle install`
-* run the script with `ruby ./app.rb`
-
-## API Coverage
-
-* Activity Details
-  * [X] Remember Me ID `remember_me_id`
-  * [X] Parent Remember Me ID `parent_remember_me_id`
-  * [X] Receipt ID `receipt_id`
-  * [X] Timestamp `timestamp`
-  * [X] Base64 Selfie URI `base64_selfie_uri`
-  * [X] Age verified `age_verified`
-  * [X] Profile `profile`
-    * [X] Selfie `selfie`
-    * [X] Full Name `full_name`
-    * [X] Given Names `given_names`
-    * [X] Family Name `family_name`
-    * [X] Mobile Number `phone_number`
-    * [X] Email Address `email_address`
-    * [X] Age / Date of Birth `date_of_birth`
-    * [X] Address `postal_address`
-    * [X] Structured Postal Address `structured_postal_address`
-    * [X] Gender `gender`
-    * [X] Nationality `nationality`
-  * [X] Application Profile `application_profile`
-    * [X] Name `name`
-    * [X] URL `url`
-    * [X] Logo `logo`
-    * [X] Receipt Background Color `receipt_bgcolor`
+The Yoti SDK can be used for the following products, follow the links for more information about each:
+1) [Yoti app integration](/docs/PROFILE.md) - Connect with already-verified customers.
+1) [Yoti Doc Scan](/docs/DOCSCAN.md) - Identity verification embedded in your website or app.
 
 ## Support
 

data/lib/yoti.rb

@@ -18,6 +18,7 @@ require_relative 'yoti/data_type/application_profile'
 require_relative 'yoti/data_type/profile'
 require_relative 'yoti/data_type/attribute'
 require_relative 'yoti/data_type/signed_time_stamp'
+require_relative 'yoti/data_type/media'
 require_relative 'yoti/data_type/image'
 require_relative 'yoti/data_type/image_jpeg'
 require_relative 'yoti/data_type/image_png'
@@ -26,7 +27,8 @@ require_relative 'yoti/data_type/document_details'
 
 require_relative 'yoti/util/age_processor'
 require_relative 'yoti/util/anchor_processor'
-require_relative 'yoti/util/log.rb'
+require_relative 'yoti/util/log'
+require_relative 'yoti/util/validation'
 
 require_relative 'yoti/activity_details'
 require_relative 'yoti/client'
@@ -47,6 +49,57 @@ require_relative 'yoti/dynamic_share_service/extension/thirdparty_attribute_exte
 require_relative 'yoti/share/extra_data'
 require_relative 'yoti/share/attribute_issuance_details'
 
+require_relative 'yoti/doc_scan/client'
+require_relative 'yoti/doc_scan/constants'
+require_relative 'yoti/doc_scan/errors'
+
+require_relative 'yoti/doc_scan/session/create/create_session_result'
+require_relative 'yoti/doc_scan/session/create/requested_check'
+require_relative 'yoti/doc_scan/session/create/requested_document_authenticity_check'
+require_relative 'yoti/doc_scan/session/create/requested_id_document_comparison_check'
+require_relative 'yoti/doc_scan/session/create/requested_face_match_check'
+require_relative 'yoti/doc_scan/session/create/requested_liveness_check'
+require_relative 'yoti/doc_scan/session/create/requested_task'
+require_relative 'yoti/doc_scan/session/create/requested_text_extraction_task'
+require_relative 'yoti/doc_scan/session/create/document_filter'
+require_relative 'yoti/doc_scan/session/create/document_restrictions_filter'
+require_relative 'yoti/doc_scan/session/create/orthogonal_restrictions_filter'
+require_relative 'yoti/doc_scan/session/create/required_document'
+require_relative 'yoti/doc_scan/session/create/required_id_document'
+require_relative 'yoti/doc_scan/session/create/sdk_config'
+require_relative 'yoti/doc_scan/session/create/notification_config'
+require_relative 'yoti/doc_scan/session/create/session_specification'
+
+require_relative 'yoti/doc_scan/session/retrieve/check_response'
+require_relative 'yoti/doc_scan/session/retrieve/resource_response'
+require_relative 'yoti/doc_scan/session/retrieve/authenticity_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/id_document_comparison_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/breakdown_response'
+require_relative 'yoti/doc_scan/session/retrieve/details_response'
+require_relative 'yoti/doc_scan/session/retrieve/document_fields_response'
+require_relative 'yoti/doc_scan/session/retrieve/document_id_photo_response'
+require_relative 'yoti/doc_scan/session/retrieve/face_map_response'
+require_relative 'yoti/doc_scan/session/retrieve/face_match_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/frame_response'
+require_relative 'yoti/doc_scan/session/retrieve/generated_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/generated_media'
+require_relative 'yoti/doc_scan/session/retrieve/generated_text_data_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/get_session_result'
+require_relative 'yoti/doc_scan/session/retrieve/id_document_resource_response'
+require_relative 'yoti/doc_scan/session/retrieve/liveness_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/liveness_resource_response'
+require_relative 'yoti/doc_scan/session/retrieve/media_response'
+require_relative 'yoti/doc_scan/session/retrieve/page_response'
+require_relative 'yoti/doc_scan/session/retrieve/recommendation_response'
+require_relative 'yoti/doc_scan/session/retrieve/report_response'
+require_relative 'yoti/doc_scan/session/retrieve/resource_container'
+require_relative 'yoti/doc_scan/session/retrieve/task_response'
+require_relative 'yoti/doc_scan/session/retrieve/text_data_check_response'
+require_relative 'yoti/doc_scan/session/retrieve/text_extraction_task_response'
+require_relative 'yoti/doc_scan/session/retrieve/zoom_liveness_resource_response'
+
+require_relative 'yoti/doc_scan/support/supported_documents'
+
 # The main module namespace of the Yoti gem
 module Yoti
   class << self

data/lib/yoti/client.rb

@@ -1,15 +1,17 @@
 module Yoti
   #
-  # Handles all the publicly accesible Yoti methods for
-  # geting data using an encrypted connect token
+  # Handles all the publicly accessible Yoti methods for
+  # getting data using an encrypted connect token
   #
   module Client
     #
     # Performs all the steps required to get the decrypted profile from an API request
     #
-    # @param encrypted_connect_token [String] token provided as a base 64 string
+    # @param [String] encrypted_connect_token
+    #   Token provided as a base 64 string
     #
-    # @return [Object] an ActivityDetails instance encapsulating the user profile
+    # @return [ActivityDetails]
+    #   An ActivityDetails instance encapsulating the user profile
     #
     def self.get_activity_details(encrypted_connect_token)
       receipt = Yoti::ProfileRequest.new(encrypted_connect_token).receipt
@@ -22,6 +24,13 @@ module Yoti
       ActivityDetails.new(receipt, user_profile, application_profile, extra_data)
     end
 
+    #
+    # Perform AML check
+    #
+    # @param [AmlProfile] aml_profile
+    #
+    # @return [<Hash>]
+    #
     def self.aml_check(aml_profile)
       Yoti::AmlCheckRequest.new(aml_profile).response
     end

data/lib/yoti/configuration.rb

@@ -3,7 +3,7 @@ module Yoti
     attr_accessor :client_sdk_id, :key_file_path, :key, :sdk_identifier,
                   :api_url, :api_port, :api_version
 
-    attr_writer :api_endpoint
+    attr_writer :api_endpoint, :doc_scan_api_endpoint
 
     # Set config variables by using a configuration block
     def initialize
@@ -18,7 +18,12 @@ module Yoti
 
     # @return [String] the API endpoint for the selected API version
     def api_endpoint
-      @api_endpoint ||= "#{@api_url}/api/#{@api_version}"
+      @api_endpoint ||= ENV['YOTI_API_URL'] || "#{@api_url}/api/#{@api_version}"
+    end
+
+    # @return [String] the Doc Scan API endpoint
+    def doc_scan_api_endpoint
+      @doc_scan_api_endpoint ||= ENV['YOTI_DOC_SCAN_API_URL'] || "#{@api_url}/idverify/#{@api_version}"
     end
 
     # Validates the configuration values set in instance variables

data/lib/yoti/data_type/age_verification.rb

@@ -37,7 +37,7 @@ module Yoti
     attr_reader :age
 
     #
-    # @param [Yoti::Attribute]
+    # @param [Yoti::Attribute] attribute
     #
     def initialize(attribute)
       raise(ArgumentError, "'#{attribute.name}' is not a valid age verification") unless /^[^:]+:(?!.*:)[0-9]+$/.match?(attribute.name)

data/lib/yoti/data_type/base_profile.rb

@@ -37,7 +37,7 @@ module Yoti
     #
     # @param [String] name
     #
-    # @returns [Array]
+    # @return [Array]
     #
     def find_attributes_starting_with(name)
       @attributes.select { |key| key.to_s.start_with?(name) }