verisec 1.0.0

data/lib/verisec/util.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # Encoding helpers shared by the transport and the resources.
+  #
+  # @api private
+  module Util
+    # Characters that stay as they are in a path segment (RFC 3986 "unreserved").
+    PATH_SAFE = /[^A-Za-z0-9\-._~]/.freeze
+
+    module_function
+
+    # One path parameter, percent-encoded as a single segment. "." and ".."
+    # are encoded too, so nothing can read them as a step up the path.
+    #
+    # @param value [String, Symbol, Integer]
+    # @param name [String] the parameter's name, for the error message
+    # @return [String]
+    def path_segment(value, name)
+      text = value.is_a?(Symbol) || value.is_a?(Integer) ? value.to_s : value
+      unless text.is_a?(String) && !text.strip.empty?
+        raise ArgumentError, "#{name} must be a non-empty String, not #{value.inspect}"
+      end
+      return text.gsub(".", "%2E") if [".", ".."].include?(text)
+
+      text.b.gsub(PATH_SAFE) { |char| format("%%%02X", char.ord) }
+    end
+
+    # A query string: nil values are left out, an Array repeats its key.
+    #
+    # @param params [Hash]
+    # @return [String] without the leading "?"
+    def query_string(params)
+      pairs = []
+      params.each do |key, value|
+        next if value.nil?
+
+        if value.is_a?(Array)
+          value.each { |item| pairs << [key.to_s, scalar(item, key)] unless item.nil? }
+        else
+          pairs << [key.to_s, scalar(value, key)]
+        end
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    # A copy of request parameters ready for the wire: keys as Strings, exactly
+    # as given (the API mixes `detectAll` and `image_front`, so key casing is
+    # never changed), nil values left out (no API field takes null), Symbols as
+    # Strings. Hashes and Arrays are copied, so the caller's input is never
+    # changed by what the library does to the copy.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def wire(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, inner), out| out[key.to_s] = wire(inner) unless inner.nil? }
+      when Array then value.map { |inner| wire(inner) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+
+    # Parses a response body: the JSON value, the text itself when it is not
+    # JSON (a proxy's error page), or nil when it is empty.
+    #
+    # @param text [String, nil]
+    # @return [Object, nil]
+    def parse_body(text)
+      return nil if text.nil? || text.empty?
+
+      text = text.dup.force_encoding(Encoding::UTF_8)
+      JSON.parse(text)
+    rescue JSON::ParserError
+      text.scrub
+    end
+
+    # What a failed answer says, from any of the shapes the API, its
+    # validation layer and the gateway use: `{"error": {"code", "message",
+    # "param"}}`, `{"error": "…"}`, `{"detail": "…" | [{"loc", "msg"}]}`,
+    # `{"error_msg": "…"}`, or plain text.
+    #
+    # @param data [Object] the parsed body
+    # @return [Hash{Symbol => String, nil}] `code`, `message`, `param`
+    def error_body(data)
+      return { code: nil, message: data.empty? ? nil : data[0, 500], param: nil } if data.is_a?(String)
+
+      body = data.is_a?(Hash) ? data : {}
+      error = body["error"]
+      return { code: string(error["code"]), message: string(error["message"]), param: string(error["param"]) } if error.is_a?(Hash)
+      return { code: string(body["code"]), message: error, param: nil } if error.is_a?(String)
+
+      detail = body["detail"]
+      return { code: "invalid_input", message: detail, param: nil } if detail.is_a?(String)
+      if detail.is_a?(Array) && !detail.empty?
+        first = detail.first.is_a?(Hash) ? detail.first : {}
+        param = first["loc"].is_a?(Array) ? first["loc"].reject { |part| part == "body" }.join(".") : nil
+        return { code: "invalid_input", message: string(first["msg"]) || "The request is not valid.", param: presence(param) }
+      end
+      return { code: nil, message: body["error_msg"], param: nil } if body["error_msg"].is_a?(String)
+
+      { code: nil, message: nil, param: nil }
+    end
+
+    # Seconds from a header value such as Retry-After; nil unless it is a
+    # non-negative number.
+    #
+    # @param value [String, nil]
+    # @return [Integer, Float, nil]
+    def parse_seconds(value)
+      text = value.to_s.strip
+      seconds = Integer(text, 10, exception: false) || Float(text, exception: false)
+      seconds if seconds && seconds >= 0 && seconds.finite?
+    end
+
+    # Compares two strings in constant time.
+    #
+    # @return [Boolean]
+    def secure_compare(left, right)
+      left = left.b
+      right = right.b
+      return false unless left.bytesize == right.bytesize
+      return OpenSSL.fixed_length_secure_compare(left, right) if OpenSSL.respond_to?(:fixed_length_secure_compare)
+
+      diff = 0
+      left.bytes.zip(right.bytes) { |a, b| diff |= a ^ b }
+      diff.zero?
+    end
+
+    # The value as a String, or nil when it is nil or blank.
+    def presence(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.strip.empty? ? nil : text
+    end
+
+    # A value for an error message: at most `limit` characters.
+    def shorten(text, limit = 80)
+      text = text.to_s
+      text.length > limit ? "#{text[0, limit - 3]}..." : text
+    end
+
+    # Why a file could not be read, without the path the message repeats.
+    def reason(error)
+      error.is_a?(SystemCallError) ? error.message.split(" @ ").first : error.class.name
+    end
+
+    # A secret shown in #inspect: its prefix only.
+    def redact(secret)
+      return "nil" if secret.nil?
+
+      prefix = secret.to_s[/\A[a-z]+_(?:[a-z]+_)?/] || ""
+      "#{prefix}[REDACTED]"
+    end
+
+    def string(value)
+      value.is_a?(String) ? value : nil
+    end
+
+    def scalar(value, key)
+      case value
+      when String then value
+      when Hash, Array then raise ArgumentError, "#{key} can't be sent as a query parameter (#{value.class})"
+      else value.to_s
+      end
+    end
+    private_class_method :string, :scalar
+  end
+end

data/lib/verisec/verisec_object.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # A result the API returned: the KYC envelope's `data`, or a Financial object.
+  # Each answer type of the spec is a subclass in {VeriSec::Types} (generated),
+  # e.g. {VeriSec::Types::FaceVerify}; nested objects are wrapped too.
+  #
+  # Read fields as methods, or with `[]` (a String or a Symbol), under the
+  # API's own names (it mixes `detectAll` and `image_front`):
+  #
+  #   result.match                        # => true
+  #   result[:similarity]                 # => 0.98
+  #   result["metadata"]["serverTime"]    # => "2026-10-05T05:35:01.160Z"
+  #   result.dig("compared", 0, "roi")    # => [102, 87, 140, 140]
+  #   result.last_response.request_id     # => "req_…"
+  #
+  # A field the answer type defines but this answer left out reads as nil; a
+  # name the type does not have raises NoMethodError, so typos don't pass
+  # silently. Fields the API added after this version of the library are still
+  # readable. Names that are not Ruby method names ("Date of Birth") are read
+  # with `[]`.
+  #
+  # The "open" results (the engine's full answer: face match, document read,
+  # sanctions screening, …) define no fields; read them as a Hash, with `[]`,
+  # `dig`, `keys` and `to_h`.
+  #
+  # `to_h` gives the plain Hash, exactly the JSON as parsed (String keys),
+  # `to_json` the JSON. Results work in pattern matching:
+  #
+  #   case result
+  #   in {match: true, similarity: Float => similarity} then ...
+  #   end
+  class VeriSecObject
+    # The fields this type defines: field name => the name of the type its
+    # value follows (a nested object, or an array's items), or nil. Generated
+    # subclasses fill it in; the base class (an object of no known type) has none.
+    FIELDS = {}.freeze
+
+    # The response this object came from, on the object an API call returned.
+    #
+    # @return [ResponseInfo, nil]
+    attr_reader :last_response
+
+    class << self
+      # Wraps parsed JSON: a Hash becomes an object of this type, an Array is
+      # wrapped item by item, anything else is returned as it is.
+      #
+      # @api private
+      # @param value [Object] parsed JSON
+      # @param last_response [ResponseInfo, nil]
+      # @return [Object]
+      def construct(value, last_response = nil)
+        case value
+        when Hash then new(value, last_response: last_response)
+        when Array then value.map { |item| construct(item) }
+        else value
+        end
+      end
+
+      # @return [Hash{String => String, nil}] see {FIELDS}
+      def fields
+        self::FIELDS
+      end
+
+      # The class for a field's value.
+      #
+      # @api private
+      # @return [Class<VeriSecObject>]
+      def field_type(key)
+        name = fields[key]
+        name ? Types.const_get(name, false) : VeriSecObject
+      end
+    end
+
+    # @param values [Hash] the object's fields (String or Symbol keys)
+    # @param last_response [ResponseInfo, nil]
+    def initialize(values = {}, last_response: nil)
+      @values = {}
+      (values || {}).each do |key, value|
+        key = key.to_s
+        @values[key] = wrap(value, self.class.field_type(key))
+      end
+      @last_response = last_response
+    end
+
+    # @param key [String, Symbol]
+    # @return [Object, nil] the field's value, or nil when it is absent
+    def [](key)
+      @values[key.to_s]
+    end
+
+    # Like Hash#dig: `result.dig(:metadata, :ctx, :userIp)`.
+    #
+    # @return [Object, nil]
+    def dig(key, *rest)
+      value = self[key]
+      rest.empty? || value.nil? ? value : value.dig(*rest)
+    end
+
+    # Like Hash#fetch: raises KeyError (or returns the default) when the field is absent.
+    #
+    # @return [Object]
+    def fetch(key, *default, &block)
+      @values.fetch(key.to_s, *default, &block)
+    end
+
+    # @return [Boolean] whether the answer has this field
+    def key?(key)
+      @values.key?(key.to_s)
+    end
+
+    # @return [Array<String>] the names of the fields this answer has, as the API spells them
+    def keys
+      @values.keys
+    end
+
+    # @return [Hash{String => Object}] the plain Hash (nested objects converted too), as the API sent it
+    def to_h
+      @values.transform_values { |value| plain(value) }
+    end
+
+    # @return [String] the object as the API's JSON
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # For Rails and other JSON encoders.
+    #
+    # @return [Hash{String => Object}]
+    def as_json(*)
+      to_h
+    end
+
+    # Same type, same fields, same values (the response info is not compared).
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+
+    # For pattern matching (`in {match: true}`).
+    #
+    # @return [Hash{Symbol => Object}]
+    def deconstruct_keys(_keys)
+      @values.transform_keys(&:to_sym)
+    end
+
+    # @return [String] the fields as pretty-printed JSON
+    def to_s
+      JSON.pretty_generate(to_h)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{JSON.generate(to_h)}>"
+    end
+
+    private
+
+    def method_missing(name, *args, &block)
+      if args.empty? && block.nil?
+        key = name.to_s
+        return @values[key] if @values.key?(key)
+        return nil if self.class.fields.key?(key)
+      end
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key = name.to_s
+      @values.key?(key) || self.class.fields.key?(key) || super
+    end
+
+    def wrap(value, type)
+      case value
+      when Hash then type.new(value)
+      when Array then value.map { |item| wrap(item, type) }
+      else value
+      end
+    end
+
+    def plain(value)
+      case value
+      when VeriSecObject then value.to_h
+      when Array then value.map { |item| plain(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/verisec/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # The gem's version: the first release of the API as the gateway serves it.
+  VERSION = "1.0.0"
+end

data/lib/verisec/webhook.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # Verifies webhook deliveries and parses their events. Works without a client
+  # (and is also `client.webhooks`).
+  #
+  #   post "/webhooks/verisec" do
+  #     payload = request.body.read
+  #     event = VeriSec::Webhook.construct_event(payload, request.env, ENV["VERISEC_WEBHOOK_SECRET"])
+  #     handle(event) if event.type == "verification.completed" # event.data
+  #     status 200
+  #   rescue VeriSec::SignatureVerificationError
+  #     halt 400
+  #   end
+  #
+  # Deliveries are signed as Standard Webhooks: `webhook-id`,
+  # `webhook-timestamp` (unix seconds) and `webhook-signature`, a
+  # space-separated list of `v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<raw body>">`
+  # (several while a secret is rotating; any match passes). The key is the
+  # base64-decoded part of the endpoint secret after `whsec_`. The `svix-id`,
+  # `svix-timestamp` and `svix-signature` names work too.
+  #
+  # `headers` can be a Hash with any spelling of the names ("Webhook-Id",
+  # :webhook_id), or a Rack env (`request.env`, with `HTTP_WEBHOOK_ID`).
+  module Webhook
+    # Seconds a signed delivery stays valid, to stop replays.
+    DEFAULT_TOLERANCE = 300
+
+    # A webhook delivery's body: `type` (`verification.completed`, `aml.hit`,
+    # `credits.low`, …), `timestamp` (ISO 8601), `environment` (`test` or
+    # `live`) and `data`.
+    class Event < VeriSecObject
+      FIELDS = { "type" => nil, "timestamp" => nil, "environment" => nil, "data" => nil }.freeze
+    end
+
+    module_function
+
+    # Verifies the signature, then parses the event.
+    #
+    # Pass the body exactly as received (a String), before any JSON parsing.
+    #
+    # @param payload [String] the raw request body
+    # @param headers [Hash, #each] the delivery's headers (or a Rack env)
+    # @param secret [String] the endpoint's signing secret (`whsec_…`)
+    # @param tolerance [Integer] maximum distance from now in seconds; 0 skips the check
+    # @return [Event] `type`, `timestamp`, `environment`, `data`
+    # @raise [SignatureVerificationError] when no signature matches, a header is
+    #   missing, or the timestamp is outside the tolerance
+    def construct_event(payload, headers, secret, tolerance: DEFAULT_TOLERANCE)
+      verify_signature!(payload, headers, secret, tolerance: tolerance)
+      body = JSON.parse(text(payload))
+      raise VeriSecError, "The webhook body is not a JSON object." unless body.is_a?(Hash)
+
+      Event.new(body)
+    end
+
+    # @param (see construct_event)
+    # @return [Boolean] true when a signature matches and the timestamp is fresh
+    def verify_signature(payload, headers, secret, tolerance: DEFAULT_TOLERANCE)
+      verify_signature!(payload, headers, secret, tolerance: tolerance)
+    rescue SignatureVerificationError
+      false
+    end
+
+    # Like {verify_signature}, but raises instead of returning false.
+    #
+    # @param (see construct_event)
+    # @return [true]
+    # @raise [SignatureVerificationError]
+    def verify_signature!(payload, headers, secret, tolerance: DEFAULT_TOLERANCE)
+      raise ArgumentError, "The webhook signing secret is missing." if secret.nil? || secret.to_s.empty?
+
+      id = header(headers, "webhook-id") || header(headers, "svix-id")
+      timestamp = header(headers, "webhook-timestamp") || header(headers, "svix-timestamp")
+      signatures = header(headers, "webhook-signature") || header(headers, "svix-signature")
+      unless id && timestamp && signatures
+        raise SignatureVerificationError, "Missing webhook-id, webhook-timestamp or webhook-signature header."
+      end
+      raise SignatureVerificationError, "Malformed webhook-timestamp header." unless timestamp.match?(/\A\d+\z/)
+      if tolerance.positive? && (Time.now.to_i - timestamp.to_i).abs > tolerance
+        raise SignatureVerificationError, "Timestamp is outside the #{tolerance} s tolerance."
+      end
+
+      expected = sign(secret, id, timestamp, payload)
+      matched = signatures.split(" ").any? do |part|
+        version, value = part.split(",", 2)
+        version == "v1" && !value.to_s.empty? && Util.secure_compare(value, expected)
+      end
+      unless matched
+        raise SignatureVerificationError,
+              "No signature matches the payload. Check the signing secret and that the body is unmodified."
+      end
+
+      true
+    end
+
+    # Valid headers for a payload, for your own tests.
+    #
+    # @param payload [String]
+    # @param secret [String] a `whsec_…` secret
+    # @param id [String, nil] the message id (a new `msg_…` when left out)
+    # @param timestamp [Integer] unix seconds
+    # @return [Hash{String => String}] `webhook-id`, `webhook-timestamp`, `webhook-signature`
+    def generate_test_headers(payload, secret, id: nil, timestamp: Time.now.to_i)
+      id ||= "msg_#{SecureRandom.hex(16)}"
+      timestamp = timestamp.to_i.to_s
+      { "webhook-id" => id, "webhook-timestamp" => timestamp, "webhook-signature" => "v1,#{sign(secret, id, timestamp, payload)}" }
+    end
+
+    def sign(secret, id, timestamp, payload)
+      secret = secret.to_s
+      key = (secret.start_with?("whsec_") ? secret.delete_prefix("whsec_") : secret).unpack1("m")
+      [OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.".b + payload.to_s.b)].pack("m0")
+    end
+
+    # A header by its lower-case name, from a Hash of any spelling or a Rack env.
+    def header(headers, name)
+      return nil if headers.nil?
+
+      wanted = name.tr("-", "_")
+      headers.each do |key, value|
+        normalized = key.to_s.downcase.tr("-", "_").delete_prefix("http_")
+        next unless normalized == wanted
+
+        value = value.first if value.is_a?(Array)
+        return value.to_s.strip unless value.nil?
+      end
+      nil
+    end
+
+    def text(payload)
+      payload.to_s.dup.force_encoding(Encoding::UTF_8)
+    end
+    private_class_method :sign, :header, :text
+  end
+end

data/lib/verisec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "pathname"
+require "securerandom"
+require "uri"
+require "zlib"
+
+require_relative "verisec/version"
+
+# The official Ruby library for the VeriSec API: identity (KYC) checks and the
+# Financial cheque, card, bank and BIN reads.
+#
+#   require "verisec"
+#
+#   client = VeriSec::Client.new(api_key: ENV["VERISEC_API_KEY"]) # sk_test_… or ak_live_…
+#   result = client.face.verify(image1: "selfie.jpg", image2: "id-photo.jpg")
+#   result.match                       # => true
+#   result.last_response.request_id    # => "req_…"
+#
+# See {VeriSec::Client} for the calls, {VeriSec::Webhook} for webhook
+# deliveries and {VeriSec::VeriSecError} for what can go wrong.
+module VeriSec
+  # Where requests go unless the client (or `VERISEC_BASE_URL`) says otherwise.
+  DEFAULT_BASE_URL = "https://verisec.mmose.me"
+end
+
+require_relative "verisec/errors"
+require_relative "verisec/util"
+require_relative "verisec/response_info"
+require_relative "verisec/verisec_object"
+require_relative "verisec/image"
+require_relative "verisec/file_input"
+require_relative "verisec/multipart"
+require_relative "verisec/webhook"
+require_relative "verisec/auth"
+require_relative "verisec/transport"
+require_relative "verisec/resource"
+require_relative "verisec/generated/types"
+require_relative "verisec/generated/resources"
+require_relative "verisec/client"