sorbet-hibp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0cdf85cd575436f967204205717c5aa3ab0fba4f40c462668d52fe45ba2f9f7
+  data.tar.gz: 3bc67bbbbc5e7bdf548565bd3a75555ac2463319f2b7df72d087450f04931575
+SHA512:
+  metadata.gz: 91c94864621aae1bdf326280868269020bb4d654145ec487b050ba11f33c553ab8071995c625eb658094e76a64e06dd339a3ec0f573b71e361525a8982bca07a
+  data.tar.gz: 19a0d5de08648c463fe3131bc609fac8934ab740f981fb753d9da402b4c71bd92781ca07f7d96619221c59cb8907605b5f998b6db13e005710d8e146a7a7dbf7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sorbeet Payments OU
+
+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,263 @@
+# HaveIBeenPwned
+
+A simple, clean Ruby wrapper for the Have I Been Pwned API v3.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'haveibeenpwned'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install haveibeenpwned
+```
+
+## Usage
+
+### Initialize the Client
+
+```ruby
+require 'haveibeenpwned'
+
+client = HaveIBeenPwned::Client.new(
+  api_key: 'your-api-key-here',
+  user_agent: 'MyApp/1.0'
+)
+```
+
+Get your API key from [haveibeenpwned.com/API/Key](https://haveibeenpwned.com/API/Key).
+
+### Breach Lookups
+
+#### Get all breaches for an account
+
+```ruby
+breaches = client.breached_account('test@example.com')
+# => [{"Name"=>"Adobe"}, {"Name"=>"LinkedIn"}]
+
+# Get full breach data
+breaches = client.breached_account('test@example.com', truncate_response: false)
+
+# Filter by domain
+breaches = client.breached_account('test@example.com', domain: 'adobe.com')
+
+# Exclude unverified breaches
+breaches = client.breached_account('test@example.com', include_unverified: false)
+```
+
+#### Get all breached email addresses for a domain
+
+```ruby
+# Requires domain verification in your HIBP dashboard
+breached = client.breached_domain('example.com')
+# => {"alias1"=>["Adobe"], "alias2"=>["Adobe", "LinkedIn"]}
+```
+
+#### Get all breaches in the system
+
+```ruby
+all_breaches = client.breaches
+# => [{"Name"=>"Adobe", "Title"=>"Adobe", ...}, ...]
+
+# Filter by domain
+adobe_breaches = client.breaches(domain: 'adobe.com')
+
+# Filter spam lists
+spam_lists = client.breaches(is_spam_list: true)
+```
+
+#### Get a single breach
+
+```ruby
+breach = client.breach('Adobe')
+# => {"Name"=>"Adobe", "Title"=>"Adobe", "Domain"=>"adobe.com", ...}
+```
+
+#### Get the latest breach
+
+```ruby
+latest = client.latest_breach
+# => {"Name"=>"...", "AddedDate"=>"2025-01-15T10:30:00Z", ...}
+```
+
+#### Get all data classes
+
+```ruby
+classes = client.data_classes
+# => ["Account balances", "Email addresses", "Passwords", ...]
+```
+
+#### Get subscribed domains
+
+```ruby
+domains = client.subscribed_domains
+# => [{"DomainName"=>"example.com", "PwnCount"=>150, ...}]
+```
+
+### Stealer Logs
+
+Requires Pwned 5+ subscription and verified domain ownership.
+
+#### Get stealer log domains for an email
+
+```ruby
+domains = client.stealer_logs_by_email('user@example.com')
+# => ["netflix.com", "spotify.com"]
+```
+
+#### Get email addresses for a website domain
+
+```ruby
+emails = client.stealer_logs_by_website_domain('netflix.com')
+# => ["user1@gmail.com", "user2@yahoo.com"]
+```
+
+#### Get email aliases for an email domain
+
+```ruby
+aliases = client.stealer_logs_by_email_domain('example.com')
+# => {"user1"=>["netflix.com"], "user2"=>["spotify.com", "netflix.com"]}
+```
+
+### Pastes
+
+```ruby
+pastes = client.pastes('test@example.com')
+# => [{"Source"=>"Pastebin", "Id"=>"8Q0BvKD8", "Title"=>"syslog", ...}]
+```
+
+### Subscription Status
+
+```ruby
+status = client.subscription_status
+# => {"SubscriptionName"=>"Pwned 3", "Rpm"=>100, ...}
+```
+
+### Pwned Passwords
+
+The Pwned Passwords API is completely separate and requires no authentication.
+
+#### Check if a password has been pwned
+
+```ruby
+count = HaveIBeenPwned::PwnedPasswords.check('password123')
+# => 123456 (number of times this password appears in breaches)
+
+# If password not found
+count = HaveIBeenPwned::PwnedPasswords.check('very-unique-password-xyz')
+# => 0
+```
+
+#### Check with padding (enhanced privacy)
+
+```ruby
+count = HaveIBeenPwned::PwnedPasswords.check('password123', padding: true)
+```
+
+#### Check a pre-computed hash
+
+```ruby
+hash = '5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8' # SHA-1 of 'password'
+count = HaveIBeenPwned::PwnedPasswords.check_hash(hash)
+# => 123456
+```
+
+#### Get raw range search results
+
+```ruby
+# Get all hash suffixes for a prefix
+results = HaveIBeenPwned::PwnedPasswords.range_search('5BAA6')
+# => "1E4C9B93F3F0682250B6CF8331B7EE68FD8:123456\n..."
+```
+
+## Error Handling
+
+The gem raises specific exceptions for different HTTP errors:
+
+```ruby
+begin
+  breaches = client.breached_account('test@example.com')
+rescue HaveIBeenPwned::NotFoundError
+  puts "Account not found in any breaches"
+rescue HaveIBeenPwned::UnauthorizedError
+  puts "Invalid API key"
+rescue HaveIBeenPwned::ForbiddenError
+  puts "Missing or invalid user agent"
+rescue HaveIBeenPwned::RateLimitError => e
+  puts "Rate limit exceeded. Retry after #{e.retry_after} seconds"
+rescue HaveIBeenPwned::BadRequestError => e
+  puts "Bad request: #{e.message}"
+rescue HaveIBeenPwned::ServiceUnavailableError
+  puts "Service temporarily unavailable"
+rescue HaveIBeenPwned::Error => e
+  puts "Unexpected error: #{e.message}"
+end
+```
+
+## Test Accounts
+
+Use test accounts on `hibp-integration-tests.com` domain with a test API key (any 32-char hex string like `00000000000000000000000000000000`):
+
+```ruby
+client = HaveIBeenPwned::Client.new(
+  api_key: '00000000000000000000000000000000',
+  user_agent: 'Testing'
+)
+
+# Test account that exists in breaches
+breaches = client.breached_account('account-exists@hibp-integration-tests.com')
+
+# Test account with spam list only
+spam = client.breached_account('spam-list-only@hibp-integration-tests.com')
+
+# Test account with stealer logs
+logs = client.breached_account('stealer-log@hibp-integration-tests.com')
+```
+
+See the [full list of test accounts](https://haveibeenpwned.com/API/v3#TestAccounts) in the API documentation.
+
+## Rate Limiting
+
+Rate limits vary by subscription level. When exceeded, a `RateLimitError` is raised with the `retry_after` attribute indicating seconds to wait:
+
+```ruby
+begin
+  breaches = client.breached_account('test@example.com')
+rescue HaveIBeenPwned::RateLimitError => e
+  sleep e.retry_after
+  retry
+end
+```
+
+## Design Philosophy
+
+This gem follows KISS, DRY, YAGNI, and shibui principles:
+
+- **Simple**: Flat API surface with instance-based configuration
+- **Clean**: Returns raw hashes, no unnecessary abstractions
+- **Minimal**: Only essential dependencies (Faraday)
+- **Clear**: Explicit error handling with semantic exceptions
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Attribution
+
+This gem uses the Have I Been Pwned API. Please ensure proper attribution when using this service in your application.
+
+Data sourced from [haveibeenpwned.com](https://haveibeenpwned.com) - check if your email has been compromised in a data breach.

data/lib/haveibeenpwned/client.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "erb"
+
+module HaveIBeenPwned
+  class Client
+    BASE_URL = "https://haveibeenpwned.com/api/v3"
+
+    attr_reader :api_key, :user_agent
+
+    def initialize(api_key:, user_agent:)
+      @api_key = api_key
+      @user_agent = user_agent
+    end
+
+    # Breaches
+
+    def breached_account(account, truncate_response: true, domain: nil, include_unverified: true)
+      params = {
+        truncateResponse: truncate_response,
+        includeUnverified: include_unverified
+      }
+      params[:domain] = domain if domain
+
+      get("/breachedaccount/#{url_encode(account)}", params)
+    end
+
+    def breached_domain(domain)
+      get("/breacheddomain/#{domain}")
+    end
+
+    def subscribed_domains
+      get("/subscribeddomains")
+    end
+
+    def breaches(domain: nil, is_spam_list: nil)
+      params = {}
+      params[:domain] = domain if domain
+      params[:isSpamList] = is_spam_list unless is_spam_list.nil?
+
+      get("/breaches", params)
+    end
+
+    def breach(name)
+      get("/breach/#{name}")
+    end
+
+    def latest_breach
+      get("/latestbreach")
+    end
+
+    def data_classes
+      get("/dataclasses")
+    end
+
+    # Stealer Logs
+
+    def stealer_logs_by_email(email)
+      get("/stealerlogsbyemail/#{url_encode(email)}")
+    end
+
+    def stealer_logs_by_website_domain(domain)
+      get("/stealerlogsbywebsitedomain/#{domain}")
+    end
+
+    def stealer_logs_by_email_domain(domain)
+      get("/stealerlogsbyemaildomain/#{domain}")
+    end
+
+    # Pastes
+
+    def pastes(account)
+      get("/pasteaccount/#{url_encode(account)}")
+    end
+
+    # Subscription
+
+    def subscription_status
+      get("/subscription/status")
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |conn|
+        conn.headers["hibp-api-key"] = api_key
+        conn.headers["user-agent"] = user_agent
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def get(path, params = {})
+      response = connection.get(path, params)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200
+        parse_json(response.body)
+      when 400
+        raise BadRequestError, parse_error_message(response)
+      when 401
+        raise UnauthorizedError, parse_error_message(response)
+      when 403
+        raise ForbiddenError, parse_error_message(response)
+      when 404
+        raise NotFoundError, parse_error_message(response)
+      when 429
+        retry_after = response.headers["retry-after"]&.to_i
+        raise RateLimitError.new(parse_error_message(response), retry_after: retry_after)
+      when 503
+        raise ServiceUnavailableError, parse_error_message(response)
+      else
+        raise Error, "Unexpected response: #{response.status} - #{response.body}"
+      end
+    end
+
+    def parse_json(body)
+      return nil if body.nil? || body.empty?
+      JSON.parse(body)
+    end
+
+    def parse_error_message(response)
+      body = parse_json(response.body)
+      body.is_a?(Hash) ? body["message"] || body["statusCode"] : response.body
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def url_encode(string)
+      ERB::Util.url_encode(string.to_s.strip)
+    end
+  end
+end

data/lib/haveibeenpwned/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module HaveIBeenPwned
+  class Error < StandardError; end
+
+  class BadRequestError < Error; end
+
+  class UnauthorizedError < Error; end
+
+  class ForbiddenError < Error; end
+
+  class NotFoundError < Error; end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil)
+      super(message)
+      @retry_after = retry_after
+    end
+  end
+
+  class ServiceUnavailableError < Error; end
+end

data/lib/haveibeenpwned/pwned_passwords.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "digest"
+
+module HaveIBeenPwned
+  class PwnedPasswords
+    BASE_URL = "https://api.pwnedpasswords.com"
+
+    class << self
+      def check(password, mode: :sha1, padding: false)
+        hash = hash_password(password, mode)
+        check_hash(hash, mode: mode, padding: padding)
+      end
+
+      def check_hash(hash, mode: :sha1, padding: false)
+        hash = hash.upcase
+        prefix = hash[0..4]
+        suffix = hash[5..-1]
+
+        response = range_search(prefix, mode: mode, padding: padding)
+
+        # Parse response and find matching suffix
+        response.each_line do |line|
+          hash_suffix, count = line.strip.split(":")
+          return count.to_i if hash_suffix == suffix
+        end
+
+        0
+      end
+
+      def range_search(prefix, mode: :sha1, padding: false)
+        params = {}
+        params[:mode] = mode.to_s if mode == :ntlm
+
+        headers = {}
+        headers["Add-Padding"] = "true" if padding
+
+        response = connection.get("/range/#{prefix}", params) do |req|
+          headers.each { |key, value| req.headers[key] = value }
+        end
+
+        raise Error, "Unexpected response: #{response.status}" unless response.status == 200
+
+        response.body
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: BASE_URL) do |conn|
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def hash_password(password, mode)
+        case mode
+        when :sha1
+          Digest::SHA1.hexdigest(password)
+        when :ntlm
+          # NTLM hashing would require additional gem, keeping simple for now
+          raise NotImplementedError, "NTLM hashing not yet implemented. Use check_hash with pre-computed NTLM hash."
+        else
+          raise ArgumentError, "Invalid mode: #{mode}. Use :sha1 or :ntlm"
+        end
+      end
+    end
+  end
+end

data/lib/haveibeenpwned/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HaveIBeenPwned
+  VERSION = "0.1.0"
+end

data/lib/haveibeenpwned.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "haveibeenpwned/version"
+require_relative "haveibeenpwned/errors"
+require_relative "haveibeenpwned/client"
+require_relative "haveibeenpwned/pwned_passwords"
+
+module HaveIBeenPwned
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: sorbet-hibp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Angelos Kapsimanis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A simple, clean Ruby client for the Have I Been Pwned API v3, supporting
+  breach lookups, pastes, stealer logs, and pwned passwords
+email:
+- angelos@sorbet.ee
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/haveibeenpwned.rb
+- lib/haveibeenpwned/client.rb
+- lib/haveibeenpwned/errors.rb
+- lib/haveibeenpwned/pwned_passwords.rb
+- lib/haveibeenpwned/version.rb
+homepage: https://github.com/sorbet-ee/haveibeenpwned.
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sorbet-ee/haveibeenpwned.
+  source_code_uri: https://github.com/sorbet-ee/haveibeenpwned.
+  changelog_uri: https://github.com/sorbet-ee/haveibeenpwned./blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby wrapper for the Have I Been Pwned API
+test_files: []