hibp-client 0.1.0

data/lib/hibp/helpers/attribute_assignment.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Helpers
+    # Hibp::Helpers::AttributeAssignment
+    #
+    #   Used to assign attributes in models
+    #
+    module AttributeAssignment
+      private
+
+      def assign_attributes(new_attributes)
+        unless new_attributes.is_a?(Hash)
+          raise ArgumentError, 'Attributes must be a Hash'
+        end
+
+        return if new_attributes.nil? || new_attributes.empty?
+
+        attributes = stringify_keys(new_attributes)
+        attributes.each { |k, v| _assign_attribute(k, v) }
+      end
+
+      def stringify_keys(hash)
+        transform_keys(hash, &:to_s)
+      end
+
+      def transform_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[yield(key)] = value
+        end
+      end
+
+      def _assign_attribute(attr_name, attr_value)
+        return unless respond_to?("#{attr_name}=")
+
+        public_send("#{attr_name}=", attr_value)
+      end
+    end
+  end
+end

data/lib/hibp/helpers/json_conversion.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Helpers
+    # Hibp::Helpers::JsonConversion
+    #
+    #   Used to convert raw API response data to the entity models
+    #
+    module JsonConversion
+      protected
+
+      # Convert raw data to the entity model
+      #
+      # @param data [Array<Hash>, Hash] - Raw data from response
+      #
+      def convert(data, &block)
+        data.is_a?(Array) ? convert_to_list(data, &block) : convert_to_entity(data, &block)
+      end
+
+      private
+
+      def convert_to_list(data, &block)
+        data.map { |d| convert_to_entity(d, &block) }
+      end
+
+      def convert_to_entity(data)
+        attributes = data.each_with_object({}) do |(key, value), hash|
+          hash[transform_key(key)] = value
+        end
+
+        yield(attributes)
+      end
+
+      def transform_key(key)
+        underscore(key.to_s).to_sym
+      end
+
+      def underscore(camel_cased_word)
+        camel_cased_word.gsub(/::/, '/')
+                        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                        .tr('-', '_')
+                        .downcase
+      end
+    end
+  end
+end

data/lib/hibp/models/breach.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Models
+    # Hibp::Models::Breach
+    #
+    #   Used to construct a "breach" model
+    #
+    #   A "breach" is an instance of a system having been compromised by an
+    #   attacker and the data disclosed.
+    #
+    #   For example, Adobe was a breach, Gawker was a breach etc.
+    #
+    #   A "breach" is an incident where data is inadvertently exposed in a vulnerable system,
+    #   usually due to insufficient access controls or security weaknesses in the software.
+    #
+    #   @see https://haveibeenpwned.com/FAQs
+    #
+    class Breach
+      include Helpers::AttributeAssignment
+
+      attr_accessor :name, :title, :domain, :description, :logo_path,
+                    :data_classes, :pwn_count,
+                    :breach_date, :added_date, :modified_date,
+                    :is_verified, :is_fabricated, :is_sensitive, :is_retired, :is_spam_list
+
+      # @param attributes [Hash] - Attributes in a hash
+      #
+      # @option attributes [String] :name  -
+      #   A name representing the breach which is unique across all other breaches.
+      #   This value never changes and may be used to name dependent assets
+      #   (such as images) but should not be shown directly to end users
+      #   (see the "title" attribute instead).
+      #
+      # @option attributes [String] :title -
+      #   A descriptive title for the breach suitable for displaying to end users.
+      #   It's unique across all breaches but individual values may change in the future
+      #   (i.e. if another breach occurs against an organisation already in the system).
+      #   If a stable value is required to reference the breach, refer to the "Name" attribute instead.
+      #
+      # @option attributes [String] :domain -
+      #   The domain of the primary website the breach occurred on.
+      #   This may be used for identifying other assets external systems may have for the site.
+      #
+      # @option attributes [Date] :breach_date -
+      #   The date (with no time) the breach originally occurred on in ISO 8601 format.
+      #   This is not always accurate — frequently breaches are discovered and reported long after the original incident.
+      #   Use this attribute as a guide only.
+      #
+      # @option attributes [DateTime] :added_date -
+      #   The date and time (precision to the minute) the breach was added to the system in ISO 8601 format.
+      #
+      # @option attributes [DateTime] :modified_date -
+      #   The date and time (precision to the minute) the breach was modified in ISO 8601 format.
+      #   This will only differ from the AddedDate attribute if other attributes
+      #   represented here are changed or data in the breach itself is changed
+      #   (i.e. additional data is identified and loaded).
+      #   It is always either equal to or greater then the AddedDate attribute, never less than.
+      #
+      # @option attributes [Integer] :pwn_count -
+      #   The total number of accounts loaded into the system.
+      #   This is usually less than the total number reported by the media due to
+      #   duplication or other data integrity issues in the source data.
+      #
+      # @option attributes [String] :description -
+      #   Contains an overview of the breach represented in HTML markup.
+      #   The description may include markup such as emphasis and strong tags as well as hyperlinks.
+      #
+      # @option attributes [Array<String>] :data_classes -
+      #   This attribute describes the nature of the data compromised in the breach and
+      #   contains an alphabetically ordered string array of impacted data classes.
+      #
+      # @option attributes [Boolean] :is_verified -
+      #   Indicates that the breach is considered unverified.
+      #   An unverified breach may not have been hacked from the indicated website.
+      #   An unverified breach is still loaded into HIBP when there's
+      #   sufficient confidence that a significant portion of the data is legitimate.
+      #
+      # @option attributes [Boolean] :is_fabricated -
+      #   Indicates that the breach is considered fabricated.
+      #   A fabricated breach is unlikely to have been hacked from the
+      #   indicated website and usually contains a large amount of manufactured data.
+      #   However, it still contains legitimate email addresses and asserts that
+      #   the account owners were compromised in the alleged breach.
+      #
+      # @option attributes [Boolean] :is_sensitive -
+      #   Indicates if the breach is considered sensitive.
+      #   The public API will not return any accounts for a breach flagged as sensitive.
+      #
+      # @option attributes [Boolean] :is_retired -
+      #   Indicates if the breach has been retired.
+      #   This data has been permanently removed and will not be returned by the API.
+      #
+      # @option attributes [Boolean] :is_spam_list -
+      #   Indicates if the breach is considered a spam list.
+      #   This flag has no impact on any other attributes but
+      #   it means that the data has not come as a result of a security compromise.
+      #
+      # @option attributes [String] :logo_path -
+      #   A URI that specifies where a logo for the breached service can be found.
+      #   Logos are always in PNG format.
+      #
+      # @raise [ArgumentError]
+      # @raise [UnknownAttributeError]
+      #
+      def initialize(attributes)
+        assign_attributes(attributes)
+      end
+
+      %i[verified fabricated sensitive retired spam_list].each do |method|
+        define_method("#{method}?") { public_send("is_#{method}") }
+      end
+    end
+  end
+end

data/lib/hibp/models/password.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Models
+    # Hibp::Models::Password
+    #
+    #   Represents password by the suffix of and
+    #   a count of how many times it appears in the data set
+    #
+    class Password
+      include Helpers::AttributeAssignment
+
+      attr_accessor :suffix, :occurrences
+
+      # @param attributes [Hash]
+      #
+      # @option attributes [String] :suffix -
+      #   Password suffix(password hash without first five symbols)
+      #
+      # @option attributes [Integer] :occurrences -
+      #   Count of how many times suffix appears in the data set
+      #
+      def initialize(attributes)
+        assign_attributes(attributes)
+      end
+    end
+  end
+end

data/lib/hibp/models/paste.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Models
+    # Hibp::Models::Paste
+    #
+    #   Used to construct a "paste" model
+    #
+    #   A "paste" is information that has been "pasted" to a publicly facing
+    #   website designed to share content such as Pastebin.
+    #
+    #   These services are favoured by hackers due to the ease of anonymously
+    #   sharing information and they're frequently the first place a breach appears.
+    #
+    #   @note In the future, these attributes may expand without the API being versioned.
+    #
+    #   @see https://haveibeenpwned.com/FAQs
+    #
+    class Paste
+      include Helpers::AttributeAssignment
+
+      attr_accessor :source, :id, :title, :date, :email_count
+
+      # @param attributes [Hash]
+      #
+      # @option attributes [String] :source -
+      #   The paste service the record was retrieved from.
+      #   Current values are:
+      #     - Pastebin
+      #     - Pastie
+      #     - Slexy
+      #     - Ghostbin
+      #     - QuickLeak
+      #     - JustPaste
+      #     - AdHocUrl
+      #     - PermanentOptOut
+      #     - OptOut
+      #
+      # @option attributes [String] :id -
+      #   The ID of the paste as it was given at the source service.
+      #   Combined with the "Source" attribute, this can be used to resolve the URL of the paste.
+      #
+      # @option attributes [String] :title -
+      #   The title of the paste as observed on the source site.
+      #   This may be null.
+      #
+      # @option attributes [String] :date -
+      #   The date and time (precision to the second) that the paste was posted.
+      #   This is taken directly from the paste site when this information is
+      #   available but may be null if no date is published.
+      #
+      # @option attributes [Integer] :email_count -
+      #   The number of emails that were found when processing the paste.
+      #   Emails are extracted by using the regular expression:
+      #   \b+(?!^.{256})[a-zA-Z0-9\.\-_\+]+@[a-zA-Z0-9\.\-_]+\.[a-zA-Z]+\b
+      #
+      def initialize(attributes)
+        assign_attributes(attributes)
+      end
+    end
+  end
+end

data/lib/hibp/parsers/breach.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Parsers
+    # Hibp::Parsers::Breach
+    #
+    #   Used to convert raw API response data to the breach entity or
+    #     array of the entities in case if response data contains multiple breaches
+    #
+    class Breach < Json
+
+      # Convert raw data to the breach entity
+      #
+      # @param response [Faraday::Response] -
+      #   Response that contains raw data for conversion
+      #
+      # @see https://haveibeenpwned.com/API/v3 (The breach model, Sample breach response)
+      #
+      # @return [Array<Hibp::Breach>, Hibp::Breach]
+      #
+      def parse_response(response)
+        super(response) do |attributes|
+          Models::Breach.new(convert_dates!(attributes))
+        end
+      end
+
+      private
+
+      def convert_dates!(attributes)
+        %i[modified_date breach_date added_date].each do |attr_key|
+          next if attributes[attr_key].nil?
+
+          type = attr_key == :breach_date ? Date : Time
+
+          attributes[attr_key] = type.parse(attributes[attr_key])
+        end
+
+        attributes
+      end
+    end
+  end
+end

data/lib/hibp/parsers/json.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Parsers
+    # Hibp::Parsers::Json
+    #
+    #   Used to parse API JSON response and transform(convert) this
+    #     raw data to the model specified by converter
+    #
+    class Json
+      include Helpers::JsonConversion
+
+      # Parse API response
+      #
+      # @param response [Faraday::Response] -
+      #   Response that contains raw data for conversion
+      #
+      # @yield [attributes] - (optional, default: nil)
+      #   Converter that used to convert complex
+      #   raw response data to the particular model representation.
+      #
+      # @note If block with conversion not set than parser returns raw data
+      #   (useful in cases when response returns array of strings)
+      #
+      # @raise [Hibp::ServiceError]
+      #
+      def parse_response(response, &block)
+        return nil if empty_response?(response)
+
+        begin
+          _, body = prepare_response(response)
+
+          block_given? ? convert(body, &block) : body
+        rescue Oj::ParseError
+          raise_error(response.body)
+        end
+      end
+
+      private
+
+      def empty_response?(response)
+        response.body.nil? || response.body.empty?
+      end
+
+      def prepare_response(response)
+        headers = response.headers
+        body = Oj.load(response.body, symbolize_keys: true)
+
+        [headers, body]
+      end
+
+      def raise_error(payload)
+        error = ServiceError.new(
+          "Unparseable response: #{payload}",
+          title: 'UNPARSEABLE_RESPONSE', status_code: 500
+        )
+
+        raise error
+      end
+    end
+  end
+end

data/lib/hibp/parsers/password.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Parsers
+    # Parsers::Password
+    #
+    #   Used to parse raw data and convert it to the password models
+    #
+    class Password
+      ROWS_SPLITTER = "\r\n"
+      ATTRIBUTES_SPLITTER = ':'
+
+      # Convert API response raw data to the passwords models.
+      #
+      # @param response [] -
+      #   Contains the suffix of every hash beginning with the specified prefix,
+      #   followed by a count of how many times it appears in the data set
+      #
+      # @return [Array<Hibp::Models::Password>]
+      #
+      def parse_response(response)
+        data = response.body
+
+        data.split(ROWS_SPLITTER).map(&method(:convert_to_password))
+      end
+
+      private
+
+      def convert_to_password(row)
+        suffix, occurrences = row.split(ATTRIBUTES_SPLITTER)
+
+        Models::Password.new(suffix: suffix, occurrences: occurrences.to_i)
+      end
+    end
+  end
+end

data/lib/hibp/parsers/paste.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hibp
+  module Parsers
+    # Hibp::Parsers::Paste
+    #
+    #   Used to convert raw API response data to the array of the paste entities
+    #
+    class Paste < Json
+      # Convert raw data to the pastes entities
+      #
+      # @param response [Faraday::Response] -
+      #   Response that contains raw data for conversion
+      #
+      # @see https://haveibeenpwned.com/API/v3 (The paste model, Sample paste response)
+      #
+      # @return [Array<Hibp::Paste>]
+      #
+      def parse_response(response)
+        super(response) { |attributes| Models::Paste.new(attributes) }
+      end
+    end
+  end
+end