identisure-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82d1c302c12ff4ecf26256974dc59b2bffe3aecdfe60b2353d3f0966832a7d13
+  data.tar.gz: c3065889a77aba5439388bc6efdd0bb9eac2d11a65a194beaf767ab4c6261775
+SHA512:
+  metadata.gz: 1a6191c000b7770c389de61ebb66b3037aed2e06078d7d16402bca6a673d740777ecb6f64635e08a2323bea5db8f53c4708b21b4b7eb37f16c0e52ad72bc3784
+  data.tar.gz: c5440e580d6521272a861e250e2f41f894aaef827989e14ba8e44d35688dcefc6aa84054a37ac485bf9fe791f10180d5b13319076bfcb96060e26a662e940858

data/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+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,105 @@
+<img align="left" height="100" style="margin-right: 10px;" src="img/icon.png">
+
+# Identisure Ruby Client
+
+[![Gem version][gem-image]][gem-url]
+[![Documentation][docs-image]][docs-url]
+[![MIT license][license-image]][license-url]
+
+[gem-image]: https://img.shields.io/gem/v/identisure-client?style=flat-square
+[gem-url]: https://rubygems.org/gems/identisure-client
+[docs-image]: https://img.shields.io/badge/github-docs-orange?logo=github&style=flat-square
+[docs-url]: https://identisure.github.io/api-client-ruby
+[license-image]: https://img.shields.io/badge/license-MIT-blue?style=flat-square
+[license-url]: https://opensource.org/license/mit
+
+API client for the [Identisure](https://developers.identisure.com) REST API.
+
+Documentation: [identisure.github.io/api-client-ruby](https://identisure.github.io/api-client-ruby)
+
+## Requirements
+
+Ruby 3.2 or later.
+
+## Supported providers
+
+- **BankID SE**: auth, sign, phone auth and sign, QR verify, age verification
+- **BankID NO**: auth, backchannel auth, sign, age verification
+- **Freja eID**: auth, backchannel auth, sign, backchannel sign, age verification
+- **MitID**: auth, backchannel auth, sign, age verification
+- **FTN** (Finnish Trust Network): auth, age verification
+- **Vipps MobilePay**: auth, backchannel auth
+- **Documents**: upload and download documents for signing
+
+## Installation
+
+```sh
+gem install identisure-client
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem 'identisure-client', '~> 0.1'
+```
+
+## Usage
+
+```ruby
+require 'identisure/client'
+
+client = Identisure::ClientBuilder.new('client_id', 'client_secret')
+                                  .environment(Identisure::Environment::STAGING)
+                                  .build
+
+session = client.bank_id_se.auth(Identisure::BankIdSe::AuthRequest.new)
+puts "Session ID: #{session.id}" if session.is_a?(Identisure::BankIdSe::Pending)
+
+result = client.bank_id_se.wait_for_auth(session.id)
+
+case result
+in Identisure::BankIdSe::Completed(ssn:, name:)
+  puts "Authenticated: #{name} (#{ssn})"
+in Identisure::BankIdSe::Failed(error:)
+  puts "Failed: #{error}"
+end
+```
+
+### Verifying callbacks
+
+Verify the `X-Signature-SHA256` header against the raw request body before parsing it:
+
+```ruby
+valid = Identisure.verify_callback_signature(raw_body, signature_header, 'hmac_secret')
+```
+
+## Development
+
+### Prerequisites
+
+- Ruby 3.2+
+- Bundler
+
+### Setup / Build / Test
+
+The test fixtures live in a Git submodule. Clone with `--recurse-submodules`, or run `git submodule update --init` in an existing clone.
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+### Release
+
+Set the version in `lib/identisure/version.rb` and commit. Then push a tag:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The release workflow checks that the tag matches the version, runs CI, publishes to RubyGems and creates a GitHub release.
+
+## Other languages
+
+[C#](https://github.com/identisure/api-client-csharp), [Dart](https://github.com/identisure/api-client-dart), [Go](https://github.com/identisure/api-client-go), [TypeScript/JavaScript](https://github.com/identisure/api-client-js), [Java/Kotlin](https://github.com/identisure/api-client-jvm), [PHP](https://github.com/identisure/api-client-php), [Python](https://github.com/identisure/api-client-py), [Rust](https://github.com/identisure/api-client-rust), [Swift](https://github.com/identisure/api-client-swift)

data/lib/identisure/age_verification.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Identisure
+  module AgeVerification
+    class Request
+      attr_reader :min_age, :max_age, :ref_id, :callback_url, :redirect_url
+
+      def initialize(min_age: nil, max_age: nil, ref_id: nil, callback_url: nil, redirect_url: nil)
+        @min_age = min_age
+        @max_age = max_age
+        @ref_id = ref_id
+        @callback_url = callback_url
+        @redirect_url = redirect_url
+      end
+
+      def to_h
+        {
+          minAge: @min_age,
+          maxAge: @max_age,
+          refId: @ref_id,
+          callbackUrl: @callback_url,
+          redirectUrl: @redirect_url,
+        }.compact
+      end
+    end
+
+    class Pending
+      attr_reader :id, :url, :min_age, :max_age
+
+      def initialize(id:, url: nil, min_age: nil, max_age: nil)
+        @id = id; @url = url; @min_age = min_age; @max_age = max_age
+      end
+
+      def deconstruct_keys(_) = { id: @id, url: @url, min_age: @min_age, max_age: @max_age }
+
+      def self.from_json(d)
+        new(id: d['id'], url: d['url'], min_age: d['minAge'], max_age: d['maxAge'])
+      end
+    end
+
+    class Completed
+      attr_reader :id, :age_verified
+
+      def initialize(id:, age_verified:)
+        @id = id; @age_verified = age_verified
+      end
+
+      def deconstruct_keys(_) = { id: @id, age_verified: @age_verified }
+
+      def self.from_json(d) = new(id: d['id'], age_verified: d['ageVerified'])
+    end
+
+    class Failed
+      attr_reader :id, :error
+
+      def initialize(id:, error:)
+        @id = id; @error = error
+      end
+
+      def deconstruct_keys(_) = { id: @id, error: @error }
+
+      def self.from_json(d) = new(id: d['id'], 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 age verification status: #{d['status'].inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/identisure/bank_id_no.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Identisure
+  module BankIdNo
+    class AuthRequest
+      attr_reader :redirect_url, :request_ssn, :request_phone, :request_email,
+                  :request_address, :ref_id, :app_callback_uri
+
+      def initialize(redirect_url: nil, request_ssn: nil, request_phone: nil,
+                     request_email: nil, request_address: nil, ref_id: nil,
+                     app_callback_uri: nil)
+        @redirect_url = redirect_url; @request_ssn = request_ssn
+        @request_phone = request_phone; @request_email = request_email
+        @request_address = request_address; @ref_id = ref_id
+        @app_callback_uri = app_callback_uri
+      end
+
+      def to_h
+        {
+          redirectUrl: @redirect_url, requestSsn: @request_ssn,
+          requestPhone: @request_phone, requestEmail: @request_email,
+          requestAddress: @request_address, refId: @ref_id,
+          appCallbackUri: @app_callback_uri
+        }.compact
+      end
+    end
+
+    class BackchannelAuthRequest
+      attr_reader :ssn, :callback_url, :ref_id
+
+      def initialize(ssn:, callback_url: nil, ref_id: nil)
+        @ssn = ssn; @callback_url = callback_url; @ref_id = ref_id
+      end
+
+      def to_h
+        { ssn: @ssn, callbackUrl: @callback_url, refId: @ref_id }.compact
+      end
+    end
+
+    class SignRequest
+      attr_reader :redirect_url, :text, :documents, :ref_id
+
+      def initialize(redirect_url: nil, text: nil, documents: nil, ref_id: nil)
+        @redirect_url = redirect_url; @text = text; @documents = documents
+        @ref_id = ref_id
+      end
+
+      def to_h
+        {
+          redirectUrl: @redirect_url, text: @text, documents: @documents,
+          refId: @ref_id
+        }.compact
+      end
+    end
+
+    class SignResult
+      attr_reader :end_user, :merchant, :document_hash
+
+      def initialize(end_user:, merchant:, document_hash:)
+        @end_user = end_user; @merchant = merchant; @document_hash = document_hash
+      end
+
+      def deconstruct_keys(_) = { end_user: @end_user, merchant: @merchant, document_hash: @document_hash }
+      def self.from_json(d) = new(end_user: d['endUser'], merchant: d['merchant'], document_hash: d['hash'])
+    end
+
+    class SignedDocument
+      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 Pending
+      attr_reader :id, :ref_id, :url, :binding_message
+
+      def initialize(id:, ref_id: nil, url: nil, binding_message: nil)
+        @id = id; @ref_id = ref_id; @url = url; @binding_message = binding_message
+      end
+
+      def deconstruct_keys(_) = { id: @id, ref_id: @ref_id, url: @url, binding_message: @binding_message }
+
+      def self.from_json(d)
+        new(id: d['id'], ref_id: d['refId'], url: d['url'], binding_message: d['bindingMessage'])
+      end
+    end
+
+    class Completed
+      attr_reader :id, :ref_id, :ssn, :name, :given_name, :surname,
+                  :phone, :email, :address, :birth_date, :pid, :bank_id,
+                  :sign_result, :signed_documents, :authenticated_at, :signed_at
+
+      def initialize(id:, ssn:, name:, given_name:, surname:, ref_id: nil,
+                     phone: nil, email: nil, address: nil, birth_date: nil,
+                     pid: nil, bank_id: nil, sign_result: nil, signed_documents: nil,
+                     authenticated_at: nil, signed_at: nil)
+        @id = id; @ref_id = ref_id; @ssn = ssn; @name = name
+        @given_name = given_name; @surname = surname; @phone = phone
+        @email = email; @address = address; @birth_date = birth_date
+        @pid = pid; @bank_id = bank_id; @sign_result = sign_result
+        @signed_documents = signed_documents
+        @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, phone: @phone, email: @email, address: @address,
+          birth_date: @birth_date, pid: @pid, bank_id: @bank_id,
+          sign_result: @sign_result, signed_documents: @signed_documents,
+          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'], phone: d['phone'],
+          email: d['email'], address: d['address'], birth_date: d['birthDate'],
+          pid: d['pid'], bank_id: d['bankId'],
+          sign_result: d['signResult'] ? SignResult.from_json(d['signResult']) : nil,
+          signed_documents: d['signedDocuments']&.map { SignedDocument.from_json(_1) },
+          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-no status: #{d['status'].inspect}")
+        end
+      end
+    end
+
+    class Endpoint
+      # @api private
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def auth(req)              = Status.from_json(@transport.post('/v3/bankid-no/auth', req.to_h))
+      def backchannel_auth(req)  = Status.from_json(@transport.post('/v3/bankid-no/backchannel/auth', req.to_h))
+      def sign(req)              = Status.from_json(@transport.post('/v3/bankid-no/sign', req.to_h))
+      def auth_status(id)        = Status.from_json(@transport.get("/v3/bankid-no/auth/#{id}"))
+      def sign_status(id)        = Status.from_json(@transport.get("/v3/bankid-no/sign/#{id}"))
+      def cancel_auth(id)        = @transport.delete("/v3/bankid-no/auth/#{id}")
+      def cancel_sign(id)        = @transport.delete("/v3/bankid-no/sign/#{id}")
+
+      def age_verification(req)
+        Identisure::AgeVerification::Status.from_json(@transport.post('/v3/bankid-no/age-verification', req.to_h))
+      end
+
+      def age_verification_status(id)
+        Identisure::AgeVerification::Status.from_json(@transport.get("/v3/bankid-no/age-verification/#{id}"))
+      end
+
+      def cancel_age_verification(id) = @transport.delete("/v3/bankid-no/age-verification/#{id}")
+
+      def wait_for_auth(id, opts: PollOptions.new) = poll(opts) { auth_status(id) }
+      def wait_for_sign(id, opts: PollOptions.new) = poll(opts) { sign_status(id) }
+
+      def wait_for_age_verification(id, opts: PollOptions.new)
+        poll_age(opts) { age_verification_status(id) }
+      end
+
+      private
+
+      def poll(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