identisure-client 0.1.0

data/lib/identisure/bank_id_se.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Identisure
+  module BankIdSe
+    # --- Requests ---
+
+    class AuthRequest
+      attr_reader :ssn, :ip_address, :callback_url, :pin_required, :intent,
+                  :org_number, :request_address, :ref_id
+
+      def initialize(ssn: nil, ip_address: nil, callback_url: nil, pin_required: nil,
+                     intent: nil, org_number: nil, request_address: nil, ref_id: nil)
+        @ssn = ssn
+        @ip_address = ip_address
+        @callback_url = callback_url
+        @pin_required = pin_required
+        @intent = intent
+        @org_number = org_number
+        @request_address = request_address
+        @ref_id = ref_id
+      end
+
+      def to_h
+        {
+          ssn: @ssn, ipAddress: @ip_address, callbackUrl: @callback_url,
+          pinRequired: @pin_required, intent: @intent, orgNumber: @org_number,
+          requestAddress: @request_address, refId: @ref_id
+        }.compact
+      end
+    end
+
+    class PhoneAuthRequest
+      attr_reader :ssn, :call_initiator, :callback_url, :pin_required, :intent,
+                  :org_number, :request_address, :ref_id
+
+      def initialize(ssn:, call_initiator:, callback_url: nil, pin_required: nil,
+                     intent: nil, org_number: nil, request_address: nil, ref_id: nil)
+        @ssn = ssn
+        @call_initiator = call_initiator
+        @callback_url = callback_url
+        @pin_required = pin_required
+        @intent = intent
+        @org_number = org_number
+        @request_address = request_address
+        @ref_id = ref_id
+      end
+
+      def to_h
+        {
+          ssn: @ssn, callInitiator: @call_initiator, callbackUrl: @callback_url,
+          pinRequired: @pin_required, intent: @intent, orgNumber: @org_number,
+          requestAddress: @request_address, refId: @ref_id
+        }.compact
+      end
+    end
+
+    class SignRequest
+      attr_reader :text, :ssn, :ip_address, :callback_url, :pin_required, :digest,
+                  :org_number, :request_address, :ref_id
+
+      def initialize(text:, ssn: nil, ip_address: nil, callback_url: nil, pin_required: nil,
+                     digest: nil, org_number: nil, request_address: nil, ref_id: nil)
+        @text = text; @ssn = ssn; @ip_address = ip_address; @callback_url = callback_url
+        @pin_required = pin_required; @digest = digest; @org_number = org_number
+        @request_address = request_address; @ref_id = ref_id
+      end
+
+      def to_h
+        {
+          text: @text, ssn: @ssn, ipAddress: @ip_address, callbackUrl: @callback_url,
+          pinRequired: @pin_required, digest: @digest, orgNumber: @org_number,
+          requestAddress: @request_address, refId: @ref_id
+        }.compact
+      end
+    end
+
+    class PhoneSignRequest
+      attr_reader :ssn, :call_initiator, :text, :callback_url, :pin_required, :digest,
+                  :org_number, :request_address, :ref_id
+
+      def initialize(ssn:, call_initiator:, text:, callback_url: nil, pin_required: nil,
+                     digest: nil, org_number: nil, request_address: nil, ref_id: nil)
+        @ssn = ssn; @call_initiator = call_initiator; @text = text
+        @callback_url = callback_url; @pin_required = pin_required; @digest = digest
+        @org_number = org_number; @request_address = request_address; @ref_id = ref_id
+      end
+
+      def to_h
+        {
+          ssn: @ssn, callInitiator: @call_initiator, text: @text,
+          callbackUrl: @callback_url, pinRequired: @pin_required, digest: @digest,
+          orgNumber: @org_number, requestAddress: @request_address, refId: @ref_id
+        }.compact
+      end
+    end
+
+    class VerifyRequest
+      attr_reader :qr_code
+
+      def initialize(qr_code:) = @qr_code = qr_code
+      def to_h = { qrCode: @qr_code }
+    end
+
+    class VerifyResponse
+      attr_reader :ssn, :name, :given_name, :surname, :age, :verified_at
+
+      def initialize(ssn:, name:, given_name:, surname:, age: nil, verified_at: nil)
+        @ssn = ssn; @name = name; @given_name = given_name; @surname = surname
+        @age = age; @verified_at = verified_at
+      end
+
+      def deconstruct_keys(_)
+        { ssn: @ssn, name: @name, given_name: @given_name, surname: @surname,
+          age: @age, verified_at: @verified_at }
+      end
+
+      def self.from_json(d)
+        new(ssn: d['ssn'], name: d['name'], given_name: d['givenName'],
+            surname: d['surname'], age: d['age'], verified_at: d['verifiedAt'])
+      end
+    end
+
+    # --- Status variants ---
+
+    class Pending
+      attr_reader :id, :ref_id, :auto_start_token, :qr_start_token, :qr_start_secret, :hint_code
+
+      def initialize(id:, ref_id: nil, auto_start_token: nil, qr_start_token: nil,
+                     qr_start_secret: nil, hint_code: nil)
+        @id = id; @ref_id = ref_id; @auto_start_token = auto_start_token
+        @qr_start_token = qr_start_token; @qr_start_secret = qr_start_secret
+        @hint_code = hint_code
+      end
+
+      def deconstruct_keys(_)
+        { id: @id, ref_id: @ref_id, auto_start_token: @auto_start_token,
+          qr_start_token: @qr_start_token, qr_start_secret: @qr_start_secret,
+          hint_code: @hint_code }
+      end
+
+      def self.from_json(d)
+        new(id: d['id'], ref_id: d['refId'], auto_start_token: d['autoStartToken'],
+            qr_start_token: d['qrStartToken'], qr_start_secret: d['qrStartSecret'],
+            hint_code: d['hintCode'])
+      end
+    end
+
+    class PendingPhone
+      attr_reader :id, :ref_id, :hint_code
+
+      def initialize(id:, ref_id: nil, hint_code: nil)
+        @id = id; @ref_id = ref_id; @hint_code = hint_code
+      end
+
+      def deconstruct_keys(_) = { id: @id, ref_id: @ref_id, hint_code: @hint_code }
+
+      def self.from_json(d)
+        new(id: d['id'], ref_id: d['refId'], hint_code: d['hintCode'])
+      end
+    end
+
+    class Device
+      attr_reader :ip_address, :uhi
+
+      def initialize(ip_address: nil, uhi: nil)
+        @ip_address = ip_address; @uhi = uhi
+      end
+
+      def deconstruct_keys(_) = { ip_address: @ip_address, uhi: @uhi }
+
+      def self.from_json(d) = new(ip_address: d['ipAddress'], uhi: d['uhi'])
+    end
+
+    class StepUp
+      attr_reader :mrtd, :face
+
+      def initialize(mrtd: nil, face: nil)
+        @mrtd = mrtd; @face = face
+      end
+
+      def deconstruct_keys(_) = { mrtd: @mrtd, face: @face }
+
+      def self.from_json(d) = new(mrtd: d['mrtd'], face: d['face'])
+    end
+
+    class Completed
+      attr_reader :id, :ref_id, :ssn, :name, :given_name, :surname,
+                  :cert_start_date, :ocsp_response, :risk, :device, :step_up,
+                  :address, :company_signatory_text,
+                  :authenticated_at, :signed_at
+
+      def initialize(id:, ssn:, name:, given_name:, surname:, ocsp_response:,
+                     ref_id: nil, cert_start_date: nil, risk: nil, device: nil, step_up: nil,
+                     address: nil, company_signatory_text: nil,
+                     authenticated_at: nil, signed_at: nil)
+        @id = id; @ref_id = ref_id; @ssn = ssn; @name = name
+        @given_name = given_name; @surname = surname
+        @cert_start_date = cert_start_date; @ocsp_response = ocsp_response
+        @risk = risk; @device = device; @step_up = step_up; @address = address
+        @company_signatory_text = company_signatory_text
+        @authenticated_at = authenticated_at; @signed_at = signed_at
+      end
+
+      def deconstruct_keys(_)
+        { id: @id, ref_id: @ref_id, ssn: @ssn, name: @name, given_name: @given_name,
+          surname: @surname, cert_start_date: @cert_start_date,
+          ocsp_response: @ocsp_response, risk: @risk, device: @device, step_up: @step_up,
+          address: @address,
+          company_signatory_text: @company_signatory_text,
+          authenticated_at: @authenticated_at, signed_at: @signed_at }
+      end
+
+      def self.from_json(d)
+        new(id: d['id'], ref_id: d['refId'], ssn: d['ssn'], name: d['name'],
+            given_name: d['givenName'], surname: d['surname'],
+            cert_start_date: d['certStartDate'], ocsp_response: d['ocspResponse'],
+            risk: d['risk'],
+            device: d['device'] ? Device.from_json(d['device']) : nil,
+            step_up: d['stepUp'] ? StepUp.from_json(d['stepUp']) : nil,
+            address: d['address'],
+            company_signatory_text: d['companySignatoryText'],
+            authenticated_at: d['authenticatedAt'], signed_at: d['signedAt'])
+      end
+    end
+
+    class Failed
+      attr_reader :id, :ref_id, :error
+
+      def initialize(id:, error:, ref_id: nil)
+        @id = id; @ref_id = ref_id; @error = error
+      end
+
+      def deconstruct_keys(_) = { id: @id, ref_id: @ref_id, error: @error }
+
+      def self.from_json(d) = new(id: d['id'], ref_id: d['refId'], error: d['error'])
+    end
+
+    class Unknown
+      attr_reader :status
+
+      def initialize(status:)
+        @status = status
+      end
+
+      def deconstruct_keys(_) = { status: @status }
+    end
+
+    module Status
+      def self.from_json(d)
+        case d['status']
+        when 'PENDING'   then Pending.from_json(d)
+        when 'COMPLETED' then Completed.from_json(d)
+        when 'FAILED'    then Failed.from_json(d)
+        when String      then Unknown.new(status: d['status'])
+        else raise IdentisureError.new(0, "Invalid bankid-se status: #{d['status'].inspect}")
+        end
+      end
+    end
+
+    module PhoneStatus
+      def self.from_json(d)
+        case d['status']
+        when 'PENDING'   then PendingPhone.from_json(d)
+        when 'COMPLETED' then Completed.from_json(d)
+        when 'FAILED'    then Failed.from_json(d)
+        when String      then Unknown.new(status: d['status'])
+        else raise IdentisureError.new(0, "Invalid bankid-se phone status: #{d['status'].inspect}")
+        end
+      end
+    end
+
+    # --- Endpoint ---
+
+    class Endpoint
+      # @api private
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def auth(req)        = Status.from_json(@transport.post('/v3/bankid-se/auth', req.to_h))
+      def phone_auth(req)  = PhoneStatus.from_json(@transport.post('/v3/bankid-se/phone/auth', req.to_h))
+      def sign(req)        = Status.from_json(@transport.post('/v3/bankid-se/sign', req.to_h))
+      def phone_sign(req)  = PhoneStatus.from_json(@transport.post('/v3/bankid-se/phone/sign', req.to_h))
+      def verify(req)      = VerifyResponse.from_json(@transport.post('/v3/bankid-se/verify', req.to_h))
+
+      def age_verification(req)
+        Identisure::AgeVerification::Status.from_json(@transport.post('/v3/bankid-se/age-verification', req.to_h))
+      end
+
+      def auth_status(id) = Status.from_json(@transport.get("/v3/bankid-se/auth/#{id}"))
+      def sign_status(id) = Status.from_json(@transport.get("/v3/bankid-se/sign/#{id}"))
+
+      def age_verification_status(id)
+        Identisure::AgeVerification::Status.from_json(@transport.get("/v3/bankid-se/age-verification/#{id}"))
+      end
+
+      def cancel_auth(id)             = @transport.delete("/v3/bankid-se/auth/#{id}")
+      def cancel_sign(id)             = @transport.delete("/v3/bankid-se/sign/#{id}")
+      def cancel_age_verification(id) = @transport.delete("/v3/bankid-se/age-verification/#{id}")
+
+      def wait_for_auth(id, opts: PollOptions.new)
+        poll_status(opts) { auth_status(id) }
+      end
+
+      def wait_for_sign(id, opts: PollOptions.new)
+        poll_status(opts) { sign_status(id) }
+      end
+
+      def wait_for_age_verification(id, opts: PollOptions.new)
+        poll_age(opts) { age_verification_status(id) }
+      end
+
+      private
+
+      def poll_status(opts)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + opts.timeout
+        loop do
+          status = yield
+          return status unless status.is_a?(Pending)
+          raise WaitError.new(timeout: true) if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep opts.interval
+        end
+      end
+
+      def poll_age(opts)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + opts.timeout
+        loop do
+          status = yield
+          return status unless status.is_a?(Identisure::AgeVerification::Pending)
+          raise WaitError.new(timeout: true) if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep opts.interval
+        end
+      end
+    end
+  end
+end

data/lib/identisure/callback.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Identisure
+  # Verifies the X-Signature-SHA256 header of a callback request. Pass the raw request body as
+  # received, before parsing it.
+  def self.verify_callback_signature(body, signature, secret)
+    expected = OpenSSL::HMAC.digest('SHA256', secret, body)
+    actual = signature.unpack1('m0')
+    actual.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(actual, expected)
+  rescue ArgumentError
+    false
+  end
+end

data/lib/identisure/client.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+require_relative 'version'
+require_relative 'environment'
+require_relative 'poll_options'
+require_relative 'error'
+require_relative 'transport'
+require_relative 'age_verification'
+require_relative 'bank_id_se'
+require_relative 'bank_id_no'
+require_relative 'freja'
+require_relative 'mit_id'
+require_relative 'ftn'
+require_relative 'vipps'
+require_relative 'document'
+require_relative 'callback'
+
+module Identisure
+  class Client
+    # @api private
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def bank_id_se = BankIdSe::Endpoint.new(@transport)
+    def bank_id_no = BankIdNo::Endpoint.new(@transport)
+    def freja      = Freja::Endpoint.new(@transport)
+    def mit_id     = MitId::Endpoint.new(@transport)
+    def ftn        = Ftn::Endpoint.new(@transport)
+    def vipps      = Vipps::Endpoint.new(@transport)
+    def document   = Document::Endpoint.new(@transport)
+  end
+
+  class ClientBuilder
+    def initialize(client_id, client_secret)
+      @client_id = client_id
+      @client_secret = client_secret
+      @environment = Environment::PRODUCTION
+      @base_url = nil
+      @http_client = nil
+      @timeout = 30
+    end
+
+    def environment(env)
+      @environment = env
+      self
+    end
+
+    def base_url(url)
+      @base_url = url
+      self
+    end
+
+    def http_client(conn)
+      @http_client = conn
+      self
+    end
+
+    # Timeout in seconds for each HTTP request. Defaults to 30.
+    def timeout(seconds)
+      raise ArgumentError, 'Timeout must be positive' unless seconds.positive?
+
+      @timeout = seconds
+      self
+    end
+
+    def build
+      base = @base_url || Environment.base_url(@environment)
+      conn = @http_client || Faraday.new
+      Client.new(Transport.new(conn, base, @client_id, @client_secret, @timeout))
+    end
+
+    def inspect = "#<#{self.class.name} client_id=#{@client_id.inspect}>"
+  end
+end

data/lib/identisure/document.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Identisure
+  module Document
+    class UploadResponse
+      attr_reader :id, :document_hash
+
+      def initialize(id:, document_hash:)
+        @id = id; @document_hash = document_hash
+      end
+
+      def deconstruct_keys(_) = { id: @id, document_hash: @document_hash }
+      def self.from_json(d) = new(id: d['id'], document_hash: d['hash'])
+    end
+
+    class Endpoint
+      # @api private
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def upload(data, filename, mime_type: 'application/pdf')
+        UploadResponse.from_json(@transport.post_multipart('/v3/document', data, filename, mime_type))
+      end
+
+      def download(id)
+        @transport.get_raw("/v3/document/#{id}")
+      end
+    end
+  end
+end

data/lib/identisure/environment.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Identisure
+  module Environment
+    PRODUCTION = :production
+    STAGING    = :staging
+
+    BASE_URLS = {
+      PRODUCTION => 'https://api.idkollen.se',
+      STAGING => 'https://stgapi.idkollen.se',
+    }.freeze
+
+    def self.base_url(env)
+      BASE_URLS.fetch(env)
+    end
+  end
+end

data/lib/identisure/error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Identisure
+  class IdentisureError < StandardError
+    attr_reader :status_code
+
+    def initialize(status_code, message)
+      @status_code = status_code
+      super("identisure: #{status_code} #{message}")
+    end
+  end
+
+  class WaitError < StandardError
+    attr_reader :timeout
+
+    def initialize(timeout:)
+      @timeout = timeout
+      super('Poll timed out')
+    end
+  end
+end