didit-sdk 1.0.0

data/lib/didit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Didit
+  VERSION = "1.0.0" # x-release-please-version
+end

data/lib/didit/webhooks/canonical_json.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Didit
+  module Webhooks
+    # Canonical JSON, the text +X-Signature-V2+ signs (docs/DESIGN.md section 9.2).
+    #
+    # It is byte for byte what the Didit backend builds in Python:
+    # +json.dumps(shorten_floats(value), sort_keys=True, separators=(",", ":"), ensure_ascii=False)+.
+    #
+    # @api private
+    module CanonicalJson
+      # Deepest nesting of objects and arrays accepted, the default of Ruby's JSON parser.
+      MAX_NESTING = 100
+
+      # What Python's json.dumps escapes in a string; everything else is written as literal UTF-8.
+      ESCAPES = (0x00..0x1f).to_h { |code| [code.chr(Encoding::UTF_8), format("\\u%04x", code)] }.merge(
+        "\"" => "\\\"", "\\" => "\\\\", "\n" => "\\n", "\r" => "\\r", "\t" => "\\t", "\b" => "\\b", "\f" => "\\f"
+      ).freeze
+      ESCAPED = /["\\\x00-\x1f]/
+
+      module_function
+
+      # The canonical JSON text of a parsed JSON value (keys may be Strings or Symbols).
+      #
+      # @raise [ArgumentError] when the value is not JSON data (NaN, Infinity, a string that is
+      #   not valid UTF-8 or holds a lone surrogate, nesting deeper than {MAX_NESTING}, another type)
+      def generate(value)
+        dump(normalize(value))
+      end
+
+      # A deep copy of a parsed JSON value with String keys and UTF-8 strings, checked to be
+      # JSON data that Python's json.dumps can write.
+      #
+      # @raise [ArgumentError] see {generate}
+      def normalize(value, depth = 0)
+        case value
+        when Hash then normalize_object(value, depth)
+        when Array then normalize_array(value, depth)
+        when String then utf8(value)
+        when Float
+          raise ArgumentError, "NaN and Infinity are not JSON numbers" unless value.finite?
+
+          value
+        when Integer, true, false, nil then value
+        else raise ArgumentError, "a #{value.class} is not JSON data"
+        end
+      end
+
+      # The canonical text of a value {normalize} returned.
+      def dump(value)
+        out = +""
+        write(value, out)
+        out
+      end
+
+      # Python's +str()+ of a parsed JSON scalar, as the backend formats the fields
+      # +X-Signature-Simple+ signs; nil for an object or an array.
+      def python_str(value)
+        case value
+        when nil then "None"
+        when true then "True"
+        when false then "False"
+        when String then value
+        when Integer then value.to_s
+        when Float then float_repr(value)
+        end
+      end
+
+      # Python's +repr()+ of a finite float: the shortest digits that round-trip (the digits
+      # Ruby's Float#to_s picks too), in scientific notation when the decimal exponent is
+      # below -4 or at least 16 (+1e-05+, +1.5e+16+), else in fixed notation (+0.0001+, +87.0+).
+      def float_repr(value)
+        return value.to_s if value.zero? # "0.0" or "-0.0", like Python
+
+        text = value.to_s
+        sign = text.start_with?("-") ? "-" : ""
+        digits, point = decimal_digits(text.delete_prefix("-"))
+        "#{sign}#{format_repr(digits, point)}"
+      end
+
+      # The significant digits of a positive Float#to_s and the position of the decimal point
+      # relative to them: the value is 0.<digits> * 10**point.
+      def decimal_digits(text)
+        mantissa, exponent = text.split("e", 2)
+        int, frac = mantissa.to_s.split(".", 2)
+        int = int.to_s
+        frac = frac.to_s
+        point = int.length + (exponent ? Integer(exponent, 10) : 0)
+        digits = "#{int}#{frac}"
+        stripped = digits.sub(/\A0+/, "")
+        point -= digits.length - stripped.length
+        [stripped.sub(/0+\z/, ""), point]
+      end
+
+      def format_repr(digits, point)
+        if point <= -4 || point > 16
+          exponent = point - 1
+          mantissa = digits.length > 1 ? "#{digits[0]}.#{digits[1..]}" : digits
+          "#{mantissa}e#{exponent.negative? ? "-" : "+"}#{exponent.abs.to_s.rjust(2, "0")}"
+        elsif point <= 0
+          "0.#{"0" * -point}#{digits}"
+        elsif point >= digits.length
+          "#{digits}#{"0" * (point - digits.length)}.0"
+        else
+          "#{digits[0, point]}.#{digits[point..]}"
+        end
+      end
+
+      def normalize_object(value, depth)
+        raise ArgumentError, "JSON nesting is deeper than #{MAX_NESTING}" if depth >= MAX_NESTING
+
+        # @type var out: Hash[String, untyped]
+        out = {}
+        value.each do |key, item|
+          name = key_name(key)
+          raise ArgumentError, "the object has the key #{name.inspect} twice" if out.key?(name)
+
+          out[name] = normalize(item, depth + 1)
+        end
+        out
+      end
+
+      def normalize_array(value, depth)
+        raise ArgumentError, "JSON nesting is deeper than #{MAX_NESTING}" if depth >= MAX_NESTING
+
+        value.map { |item| normalize(item, depth + 1) }
+      end
+
+      def key_name(key)
+        case key
+        when String then utf8(key)
+        when Symbol then utf8(key.name)
+        else raise ArgumentError, "an object key must be a String or a Symbol, not a #{key.class}"
+        end
+      end
+
+      def utf8(value)
+        text =
+          case value.encoding
+          when Encoding::UTF_8 then value
+          when Encoding::BINARY, Encoding::US_ASCII then value.dup.force_encoding(Encoding::UTF_8)
+          else value.encode(Encoding::UTF_8)
+          end
+        raise ArgumentError, "a string is not valid UTF-8 or holds a lone surrogate" unless text.valid_encoding?
+
+        text
+      rescue EncodingError
+        raise ArgumentError, "a string cannot be converted to UTF-8"
+      end
+
+      def write(value, out)
+        case value
+        when Hash then write_object(value, out)
+        when Array then write_array(value, out)
+        when String then write_string(value, out)
+        when Float then out << (value.modulo(1).zero? ? value.to_i.to_s : float_repr(value))
+        when nil then out << "null"
+        else out << value.to_s # Integer, true, false
+        end
+      end
+
+      def write_object(value, out)
+        out << "{"
+        value.keys.sort!.each_with_index do |key, index|
+          out << "," if index.positive?
+          write_string(key, out)
+          out << ":"
+          write(value[key], out)
+        end
+        out << "}"
+      end
+
+      def write_array(value, out)
+        out << "["
+        value.each_with_index do |item, index|
+          out << "," if index.positive?
+          write(item, out)
+        end
+        out << "]"
+      end
+
+      def write_string(value, out)
+        out << "\"" << value.gsub(ESCAPED, ESCAPES) << "\""
+      end
+    end
+  end
+end

data/lib/didit/webhooks/client_methods.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Didit
+  module Webhooks
+    # Adds {Didit::Webhooks.verify} and {Didit::Webhooks.verify_parsed} to +client.webhooks+,
+    # next to +client.webhooks.destinations+. They need no API key and send no request.
+    module ClientMethods
+      # See {Didit::Webhooks.verify}.
+      #
+      # @return [Event]
+      def verify(raw_body, headers, secret, tolerance: DEFAULT_TOLERANCE, allow_simple: false, now: nil)
+        Webhooks.verify(raw_body, headers, secret, tolerance: tolerance, allow_simple: allow_simple, now: now)
+      end
+
+      # See {Didit::Webhooks.verify_parsed}.
+      #
+      # @return [Event]
+      def verify_parsed(payload, headers, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+        Webhooks.verify_parsed(payload, headers, secret, tolerance: tolerance, now: now)
+      end
+    end
+  end
+end

data/lib/didit/webhooks/events.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Didit
+  module Webhooks
+    # A webhook event (docs/DESIGN.md section 9.4); {Didit::Webhooks.verify} returns the subclass
+    # for its +webhook_type+.
+    #
+    # Every field Didit sent stays readable with {#[]} and {#to_h}, typed or not.
+    class Event < Didit::Model
+      # Unique id of the event; retries carry the same id, so use it to drop duplicates.
+      field :event_id, "event_id", :string
+      # Read by #webhook_type, which falls back to +event_type+.
+      fields[:webhook_type] = ["webhook_type", :string]
+      # Unix seconds when the delivery was signed (X-Timestamp repeats it).
+      field :timestamp, "timestamp", :integer
+      # Unix seconds when the event happened, as sent.
+      field :created_at, "created_at", :integer
+      # The Didit application the event belongs to.
+      field :application_id, "application_id", :string
+      # +"live"+ or +"sandbox"+.
+      field :environment, "environment", :string
+
+      # Builds the event class that matches the payload's +webhook_type+ (or +event_type+).
+      #
+      # @api private
+      def self.build(payload, verified_by = nil)
+        data = payload.transform_keys(&:to_s) # a copy: the model freezes what it wraps
+        type = data["webhook_type"]
+        type = data["event_type"] unless type.is_a?(String)
+        klass = type.is_a?(String) ? EVENT_CLASSES.fetch(type, UnknownEvent) : UnknownEvent
+        klass.new(data, verified_by: verified_by)
+      end
+
+      # The signature header that verified the delivery (+"X-Signature"+, +"X-Signature-V2"+,
+      # their +-Previous+ variants, +"X-Signature-Simple"+ or +"X-Signature-Simple-Previous"+);
+      # nil for an event built with {Didit::Webhooks.parse_event}.
+      #
+      # @return [String, nil]
+      attr_reader :verified_by
+
+      # @param data [Hash] the parsed JSON body
+      # @param verified_by [String, nil] the header that verified it
+      def initialize(data = {}, verified_by: nil)
+        super(data)
+        @verified_by = verified_by
+      end
+
+      # The event type, for example +"status.updated"+. Callbacks that name it +event_type+
+      # (+kyb.registry_search.resolved+) report that value.
+      #
+      # @return [String, nil]
+      def webhook_type
+        value = self["webhook_type"]
+        return value if value.is_a?(String)
+
+        fallback = self["event_type"]
+        fallback.is_a?(String) ? fallback : value
+      end
+
+      # Whether a signature covered the whole body. False when only the deprecated
+      # X-Signature-Simple matched (it signs timestamp, session_id, status and webhook_type,
+      # nothing else): re-fetch the record from the API before trusting any other field.
+      # Also false for an event built with {Didit::Webhooks.parse_event}.
+      def body_authenticated?
+        Verifier::FULL_BODY.include?(@verified_by)
+      end
+    end
+
+    # Fields of the session events, +status.updated+ and +data.updated+.
+    class SessionEvent < Event
+      field :session_id, "session_id", :string
+      # Set on business (KYB) sessions, where it equals session_id.
+      field :business_session_id, "business_session_id", :string
+      # +"user"+ or +"business"+.
+      field :session_kind, "session_kind", :string
+      field :status, "status", :string
+      field :workflow_id, "workflow_id", :string
+      field :workflow_version, "workflow_version", :any
+      field :vendor_data, "vendor_data", :string
+      field :metadata, "metadata", :any
+      # The session decision, the shape +sessions.retrieve_decision+ returns.
+      field :decision, "decision", "SessionDecision"
+      # The steps the user must redo and why, when status is Resubmitted.
+      field :resubmit_info, "resubmit_info", :any
+    end
+
+    # +status.updated+: a verification session changed status.
+    class StatusUpdatedEvent < SessionEvent
+      WEBHOOK_TYPE = "status.updated"
+    end
+
+    # +data.updated+: the data of a verification session changed.
+    class DataUpdatedEvent < SessionEvent
+      WEBHOOK_TYPE = "data.updated"
+    end
+
+    # Fields of the user events.
+    class UserEvent < Event
+      field :vendor_user_id, "vendor_user_id", :string
+      field :vendor_data, "vendor_data", :string
+      field :status, "status", :string
+    end
+
+    # +user.status.updated+: a user changed status.
+    class UserStatusUpdatedEvent < UserEvent
+      WEBHOOK_TYPE = "user.status.updated"
+    end
+
+    # +user.data.updated+: the data of a user changed.
+    class UserDataUpdatedEvent < UserEvent
+      WEBHOOK_TYPE = "user.data.updated"
+    end
+
+    # Fields of the business events.
+    class BusinessEvent < Event
+      field :vendor_business_id, "vendor_business_id", :string
+      field :vendor_data, "vendor_data", :string
+      field :status, "status", :string
+    end
+
+    # +business.status.updated+: a business changed status.
+    class BusinessStatusUpdatedEvent < BusinessEvent
+      WEBHOOK_TYPE = "business.status.updated"
+    end
+
+    # +business.data.updated+: the data of a business changed.
+    class BusinessDataUpdatedEvent < BusinessEvent
+      WEBHOOK_TYPE = "business.data.updated"
+    end
+
+    # Fields of the transaction monitoring events.
+    class TransactionEvent < Event
+      # Didit's transaction id.
+      field :transaction_id, "transaction_id", :string
+      # The transaction id you sent.
+      field :txn_id, "txn_id", :string
+      field :status, "status", :string
+      field :score, "score", :float
+      field :severity, "severity", :string
+      # A decimal string, exactly as sent.
+      field :amount, "amount", :any
+      field :currency, "currency", :string
+      field :direction, "direction", :string
+      field :action_required, "action_required", :boolean
+    end
+
+    # +transaction.created+: a transaction was created.
+    class TransactionCreatedEvent < TransactionEvent
+      WEBHOOK_TYPE = "transaction.created"
+    end
+
+    # +transaction.status.updated+: a transaction changed status.
+    class TransactionStatusUpdatedEvent < TransactionEvent
+      WEBHOOK_TYPE = "transaction.status.updated"
+    end
+
+    # +travel_rule.status.updated+: the Travel Rule status of a transaction changed.
+    class TravelRuleStatusUpdatedEvent < Event
+      WEBHOOK_TYPE = "travel_rule.status.updated"
+
+      field :transaction_id, "transaction_id", :string
+      field :txn_id, "txn_id", :string
+      field :travel_rule_status, "travel_rule_status", :string
+      field :rail, "rail", :string
+      field :direction, "direction", :string
+    end
+
+    # +activity.created+: an activity was recorded; read other fields with #[].
+    class ActivityCreatedEvent < Event
+      WEBHOOK_TYPE = "activity.created"
+    end
+
+    # +workflow.compliance_changed+: the compliance state of a workflow changed.
+    class WorkflowComplianceChangedEvent < Event
+      WEBHOOK_TYPE = "workflow.compliance_changed"
+
+      field :workflow_id, "workflow_id", :string
+    end
+
+    # +kyb.registry_search.resolved+: an asynchronous KYB registry search (+kyb.search+ with
+    # +webhook_url+) finished.
+    #
+    # Didit sends this callback unsigned (header +X-Didit-Unsigned-Callback: true+, the type in
+    # +event_type+), so {Didit::Webhooks.verify} rejects it with +:missing_signature+. Read it with
+    # {Didit::Webhooks.parse_event}, treat it as untrusted, and fetch the result from the API.
+    class KybRegistrySearchResolvedEvent < Event
+      WEBHOOK_TYPE = "kyb.registry_search.resolved"
+
+      # The search request id +kyb.search+ returned.
+      field :request_id, "request_id", :string
+      field :vendor_data, "vendor_data", :string
+      field :metadata, "metadata", :any
+      # For example +"resolved"+.
+      field :search_status, "search_status", :string
+      field :search_resolved, "search_resolved", :boolean
+      # The registry result with the candidate companies.
+      field :kyb_registry, "kyb_registry", :any
+    end
+
+    # An event type this version of the SDK does not know; the whole payload stays readable
+    # with #[] and #to_h.
+    class UnknownEvent < Event
+    end
+
+    # The event class of each +webhook_type+; any other type is an {UnknownEvent}.
+    EVENT_CLASSES = {
+      StatusUpdatedEvent::WEBHOOK_TYPE => StatusUpdatedEvent,
+      DataUpdatedEvent::WEBHOOK_TYPE => DataUpdatedEvent,
+      UserStatusUpdatedEvent::WEBHOOK_TYPE => UserStatusUpdatedEvent,
+      UserDataUpdatedEvent::WEBHOOK_TYPE => UserDataUpdatedEvent,
+      BusinessStatusUpdatedEvent::WEBHOOK_TYPE => BusinessStatusUpdatedEvent,
+      BusinessDataUpdatedEvent::WEBHOOK_TYPE => BusinessDataUpdatedEvent,
+      ActivityCreatedEvent::WEBHOOK_TYPE => ActivityCreatedEvent,
+      TransactionCreatedEvent::WEBHOOK_TYPE => TransactionCreatedEvent,
+      TransactionStatusUpdatedEvent::WEBHOOK_TYPE => TransactionStatusUpdatedEvent,
+      TravelRuleStatusUpdatedEvent::WEBHOOK_TYPE => TravelRuleStatusUpdatedEvent,
+      WorkflowComplianceChangedEvent::WEBHOOK_TYPE => WorkflowComplianceChangedEvent,
+      KybRegistrySearchResolvedEvent::WEBHOOK_TYPE => KybRegistrySearchResolvedEvent
+    }.freeze
+  end
+end

data/lib/didit/webhooks/headers.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Didit
+  module Webhooks
+    # The webhook headers of a request, read from whatever the framework has.
+    #
+    # Accepts a Hash with header names in any case, a Rack env (+HTTP_X_SIGNATURE_V2+, which is
+    # also what Rails +request.headers+ and Sinatra +request.env+ yield), or any object whose
+    # +each+ yields +[name, value]+ pairs (Net::HTTPHeader, an Array of pairs). Values may be
+    # Strings or Arrays of Strings. Empty values count as absent.
+    #
+    # @api private
+    class Headers
+      # Header names (lower case) the verifier reads.
+      WANTED = [
+        HEADER_SIGNATURE, HEADER_SIGNATURE_V2, HEADER_SIGNATURE_SIMPLE,
+        HEADER_SIGNATURE_PREVIOUS, HEADER_SIGNATURE_V2_PREVIOUS, HEADER_SIGNATURE_SIMPLE_PREVIOUS,
+        HEADER_TIMESTAMP
+      ].map(&:downcase).freeze
+
+      # A well-formed signature: 64 lowercase hex characters.
+      HEX = /\A[0-9a-f]{64}\z/
+
+      # @raise [Didit::ConfigurationError] when +source+ cannot be enumerated
+      def initialize(source)
+        unless source.respond_to?(:each)
+          raise ConfigurationError,
+                "headers must be a Hash, a Rack env or [name, value] pairs, not #{source.class}."
+        end
+
+        @values = {}
+        source.each { |name, value| add(name, value) }
+      end
+
+      # Whether the header has a non-empty value.
+      def present?(name)
+        !parts(name).empty?
+      end
+
+      # The well-formed signatures a header carries. A proxy may have joined repeated
+      # headers with commas, so every comma-separated part counts.
+      def signatures(name)
+        parts(name).grep(HEX)
+      end
+
+      # The first non-empty value of +X-Timestamp+, stripped.
+      def timestamp
+        values(HEADER_TIMESTAMP).first
+      end
+
+      private
+
+      def add(name, value)
+        key = header_key(name)
+        return unless key && WANTED.include?(key)
+
+        (value.is_a?(Array) ? value : [value]).each do |item|
+          item = item.to_s if item.is_a?(Integer)
+          next unless item.is_a?(String)
+
+          text = item.b.strip
+          (@values[key] ||= []) << text unless text.empty?
+        end
+      end
+
+      def header_key(name)
+        name = name.name if name.is_a?(Symbol)
+        return unless name.is_a?(String)
+
+        key = name.b.strip.downcase
+        key.start_with?("http_") ? key.delete_prefix("http_").tr("_", "-") : key
+      end
+
+      def values(name)
+        @values.fetch(name.downcase, [])
+      end
+
+      def parts(name)
+        values(name).flat_map { |value| value.split(",").map(&:strip) }.reject(&:empty?)
+      end
+    end
+  end
+end