pwned 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca12ee3bc8b9cc61d462c9d373c18830f633b018c54661eee21f8045b7ce27c4
-  data.tar.gz: 72a1bf40821939dd027b0f5523e21db5037a4a19dedbe4f8d4bb486d33055a2f
+  metadata.gz: 502db43dbcbc77b9ea32dbac1b642d4f682f3969b810b13c2ec02b381c1b50e9
+  data.tar.gz: 5ef819185c54637d5544b7fd27134d1ae61c07ed2eaf464b7040e39fa8b15937
 SHA512:
-  metadata.gz: 6258fd06e590b92865957056245670e9b482766b8b249608c1981561ad8ce774068f79f3a16ee80b6292176676749b8ac5a89cff6bcefeaa58ca23d5bbca5f35
-  data.tar.gz: c9f1a8a256f56c382eb7f1b6a6517b05769d982e87d9a19a601652488159d4d97745d74edf2daa18ffb7b4479be81d4299b1fbbd860b91dd8465aff3c2452bb6
+  metadata.gz: fd00a0191f6d8a379ef7380cda0e7de42bdcc996483c45256185c535fb16d6a61b40a850d0f9383efda0e4441cde66ec5e24b73152a0e9af3d78da9b74a3a63f
+  data.tar.gz: bf4299bd181ff6d7b37754ed3cfefd52f9ea5fb72f9219b48a403137d5950c530be60ec85f9dfe58f412d1dbcbdb7958e0e0dc062ff8006728aa5d454899c6ae

data/.travis.yml

@@ -1,12 +1,23 @@
 sudo: false
 language: ruby
+
+env:
+  matrix:
+    - RAILS_VERSION=4.2.0
+    - RAILS_VERSION=5.0.0
+    - RAILS_VERSION=5.1.0
+    - RAILS_VERSION=5.2.0.rc1
+
 rvm:
   - 2.5.0
   - 2.4.0
   - 2.3.0
   - jruby
   - ruby-head
+
 before_install: gem install bundler -v 1.16.1
+
 matrix:
   allow_failures:
-    - rvm: ruby-head
+    - rvm: ruby-head
+    - env: RAILS_VERSION=5.2.0.rc1

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog for `Pwned`
+
+## Ongoing [☰](https://github.com/philnash/pwned/compare/v1.1.0...master)
+
+## 1.1.0 (March 12, 2018) [☰](https://github.com/philnash/pwned/commits/v1.1.0)
+
+* Major updates
+  * Refactors exception handling with built in Ruby method ([PR #1](https://github.com/philnash/pwned/pull/1) thanks [@kpumuk](https://github.com/kpumuk))
+  * Passwords must be strings, the initializer will raise a `TypeError` unless `password.is_a? String`. ([dbf7697](https://github.com/philnash/pwned/commit/dbf7697e878d87ac74aed1e715cee19b73473369))
+  * Added Ruby on Rails validator ([PR #3](https://github.com/philnash/pwned/pull/3) & [PR #6](https://github.com/philnash/pwned/pull/6))
+  * Added simplified accessors `Pwned.pwned?` and `Pwned.pwned_count` ([PR #4](https://github.com/philnash/pwned/pull/4))
+
+* Minor updates
+  * SHA1 is only calculated once
+  * Frozen string literal to make sure Ruby does not copy strings over and over again
+  * Removal of `@match_data`, since we only use it to retrieve the counter. Caching the counter instead (all [PR #2](https://github.com/philnash/pwned/pull/2) thanks [@kpumuk](https://github.com/kpumuk))
+
+## 1.0.0 (March 6, 2018) [☰](https://github.com/philnash/pwned/commits/v1.0.0)
+
+Initial release. Includes basic features for checking passwords and their count from the Pwned Passwords API. Allows setting of request headers and other options for open-uri.

data/Gemfile

@@ -4,3 +4,6 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in pwned.gemspec
 gemspec
+
+# Allows to switch Rails version in the build matrix
+gem "activemodel", ENV["RAILS_VERSION"] ? "~> #{ENV["RAILS_VERSION"]}" : nil

data/README.md

@@ -1,5 +1,9 @@
 # Pwned
 
+An easy, Ruby way to use the Pwned Passwords API.
+
+[![Build Status](https://travis-ci.org/philnash/pwned.svg?branch=master)](https://travis-ci.org/philnash/pwned)
+
 Troy Hunt's [Pwned Passwords API V2](https://haveibeenpwned.com/API/v2#PwnedPasswords) allows you to check if a password has been found in any of the huge data breaches.
 
 `Pwned` is a Ruby library to use the Pwned Passwords API's [k-Anonymity model](https://www.troyhunt.com/ive-just-launched-pwned-passwords-version-2/#cloudflareprivacyandkanonymity) to test a password against the API without sending the entire password to the service.
@@ -30,6 +34,8 @@ To test a password against the API, instantiate a `Pwned::Password` object and t
 password = Pwned::Password.new("password")
 password.pwned?
 #=> true
+password.pwned_count
+#=> 3303003
 ```
 
 You can also check how many times the password appears in the dataset.
@@ -51,7 +57,16 @@ rescue Pwned::Error => e
 end
 ```
 
-### Advanced
+Most of the times you only care if the password has been pwned before or not. You can use simplified accessors to check whether the password has been pwned, or how many times it was pwned:
+
+```ruby
+Pwned.pwned?("password")
+#=> true
+Pwned.pwned_count("password")
+#=> 3303003
+```
+
+#### Advanced
 
 You can set options and headers to be used with `open-uri` when making the request to the API. HTTP headers must be string keys and the [other options are available in the `OpenURI::OpenRead` module](https://ruby-doc.org/stdlib-2.5.0/libdoc/open-uri/rdoc/OpenURI/OpenRead.html#method-i-open).
 
@@ -59,9 +74,83 @@ You can set options and headers to be used with `open-uri` when making the reque
 password = Pwned::Password.new("password", { 'User-Agent' => 'Super fun new user agent' })
 ```
 
+### ActiveRecord Validator
+
+There is a custom validator available for your ActiveRecord models:
+
+```ruby
+class User < ApplicationRecord
+  validates :password, pwned: true
+  # or
+  validates :password, pwned: { message: "has been pwned %{count} times" }
+end
+```
+
+#### I18n
+
+You can change the error message using I18n (use `%{count}` to interpolate the number of times the password was seen in the data breaches):
+
+```yaml
+en:
+  errors:
+    messages:
+      pwned: has been pwned %{count} times
+      pwned_error: might be pwned
+```
+
+#### Threshold
+
+If you are ok with the password appearing a certain number of times before you decide it is invalid, you can set a threshold. The validator will check whether the `pwned_count` is greater than the threshold.
+
+```ruby
+class User < ApplicationRecord
+  # The record is marked as valid if the password has been used once in the breached data
+  validates :password, pwned: { threshold: 1 }
+end
+```
+
+#### Network Errors Handling
+
+By default the record will be treated as valid when we cannot reach the [haveibeenpwned.com](https://haveibeenpwned.com/) servers. This can be changed with the `:on_error` validator parameter:
+
+```ruby
+class User < ApplicationRecord
+  # The record is marked as valid on network errors.
+  validates :password, pwned: true
+  validates :password, pwned: { on_error: :valid }
+
+  # The record is marked as invalid on network errors
+  # (error message "could not be verified against the past data breaches".)
+  validates :password, pwned: { on_error: :invalid }
+
+  # The record is marked as invalid on network errors with custom error.
+  validates :password, pwned: { on_error: :invalid, error_message: "might be pwned" }
+
+  # We will raise an error on network errors.
+  # This means that `record.valid?` will raise `Pwned::Error`.
+  # Not recommended to use in production.
+  validates :password, pwned: { on_error: :raise_error }
+
+  # Call custom proc on error. For example, capture errors in Sentry,
+  # but do not mark the record as invalid.
+  validates :password, pwned: {
+    on_error: ->(record, error) { Raven.capture_exception(error) }
+  }
+end
+```
+
+#### Custom Request Options
+
+You can configure network requests made from the validator using `:request_options` (see [OpenURI::OpenRead#open](http://ruby-doc.org/stdlib-2.5.0/libdoc/open-uri/rdoc/OpenURI/OpenRead.html#method-i-open) for the list of available options, string keys represent custom network request headers, e.g. `"User-Agent"`):
+
+```ruby
+  validates :password, pwned: {
+    request_options: { read_timeout: 5, open_timeout: 1, "User-Agent" => "Super fun user agent" }
+  }
+```
+
 ## TODO
 
-- [ ] Rails validator
 - [ ] Devise plugin
 
 ## Development

data/lib/locale/en.yml

@@ -0,0 +1,5 @@
+en:
+  errors:
+    messages:
+      pwned: has previously appeared in a data breach and should not be used
+      pwned_error: could not be verified against the past data breaches

data/lib/pwned.rb

@@ -1,6 +1,29 @@
+# frozen_string_literal: true
+
 require "pwned/version"
 require "pwned/error"
 require "pwned/password"
 
+begin
+  # Load Rails and our custom validator
+  require "active_model"
+  require "pwned/pwned_validator"
+
+  # Initialize I18n (validation error message)
+  require "active_support/i18n"
+  I18n.load_path.concat Dir[File.expand_path('locale/*.yml', __dir__)]
+rescue LoadError
+  # Not a Rails project, no need to do anything
+end
+
 module Pwned
+  # Returns true when the password has been pwned.
+  def self.pwned?(password, request_options={})
+    Pwned::Password.new(password, request_options).pwned?
+  end
+
+  # Returns number of times the password has been pwned.
+  def self.pwned_count(password, request_options={})
+    Pwned::Password.new(password, request_options).pwned_count
+  end
 end

data/lib/pwned/error.rb

@@ -1,13 +1,9 @@
+# frozen_string_literal: true
+
 module Pwned
   class Error < StandardError
-    attr_reader :original_error
-
-    def initialize(message, original_error)
-      @original_error = original_error
-      super(message)
-    end
   end
 
   class TimeoutError < Error
   end
-end
+end

data/lib/pwned/password.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "digest"
 require "open-uri"
 
@@ -5,51 +7,66 @@ module Pwned
   class Password
     API_URL = "https://api.pwnedpasswords.com/range/"
     HASH_PREFIX_LENGTH = 5
+    SHA1_LENGTH = 40
     DEFAULT_REQUEST_OPTIONS = {
       "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}"
-    }
+    }.freeze
 
     attr_reader :password
 
     def initialize(password, request_options={})
+      raise TypeError, "password must be of type String" unless password.is_a? String
       @password = password
       @request_options = DEFAULT_REQUEST_OPTIONS.merge(request_options)
     end
 
+    # Returns the full SHA1 hash of the given password.
     def hashed_password
-      Digest::SHA1.hexdigest(password).upcase
+      @hashed_password ||= Digest::SHA1.hexdigest(password).upcase
     end
 
+    # Returns true when the password has been pwned.
     def pwned?
-      !!match_data
+      pwned_count > 0
     end
 
+    # Returns number of times the password has been pwned.
     def pwned_count
-      match_data ? match_data[1].to_i : 0
+      @pwned_count ||= fetch_pwned_count
     end
 
     private
 
-    def hashes
-      @hashes || get_hashes
+    def fetch_pwned_count
+      suffix = hashed_password_suffix
+      for_each_response_line do |line|
+        next unless line.start_with?(suffix)
+        # Count starts after the suffix, followed by a colon
+        return line[(SHA1_LENGTH-HASH_PREFIX_LENGTH+1)..-1].to_i
+      end
+
+      # The hash was not found, we can assume the password is not pwned [yet]
+      0
     end
 
-    def get_hashes
+    def for_each_response_line(&block)
       begin
-        open("#{API_URL}#{hashed_password[0..(HASH_PREFIX_LENGTH-1)]}", @request_options) do |io|
-          @hashes = io.read
+        open("#{API_URL}#{hashed_password_prefix}", @request_options) do |io|
+          io.each_line(&block)
         end
-        @hashes
       rescue Timeout::Error => e
-        raise Pwned::TimeoutError.new(e.message, e)
+        raise Pwned::TimeoutError, e.message
       rescue => e
-        raise Pwned::Error.new(e.message, e)
+        raise Pwned::Error, e.message
       end
     end
 
-    def match_data
-      @match_data ||= hashes.match(/#{hashed_password[HASH_PREFIX_LENGTH..-1]}:(\d+)/)
+    def hashed_password_prefix
+      hashed_password[0...HASH_PREFIX_LENGTH]
     end
 
+    def hashed_password_suffix
+      hashed_password[HASH_PREFIX_LENGTH..-1]
+    end
   end
-end
+end

data/lib/pwned/pwned_validator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class PwnedValidator < ActiveModel::EachValidator
+  # We do not want to break customer sign-up process when the service is down.
+  DEFAULT_ON_ERROR = :valid
+  DEFAULT_THRESHOLD = 0
+
+  def validate_each(record, attribute, value)
+    begin
+      pwned_check = Pwned::Password.new(value, request_options)
+      if pwned_check.pwned_count > threshold
+        record.errors.add(attribute, :pwned, options.merge(count: pwned_check.pwned_count))
+      end
+    rescue Pwned::Error => error
+      case on_error
+      when :invalid
+        record.errors.add(attribute, :pwned_error, options.merge(message: options[:error_message]))
+      when :valid
+        # Do nothing, consider the record valid
+      when Proc
+        on_error.call(record, error)
+      else
+        raise
+      end
+    end
+  end
+
+  def on_error
+    options[:on_error] || DEFAULT_ON_ERROR
+  end
+
+  def request_options
+    options[:request_options] || {}
+  end
+
+  def threshold
+    threshold = options[:threshold] || DEFAULT_THRESHOLD
+    raise TypeError, "PwnedValidator option 'threshold' must be of type Integer" unless threshold.is_a? Integer
+    threshold
+  end
+end

data/lib/pwned/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Pwned
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/pwned.gemspec

@@ -16,8 +16,6 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.16"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pwned
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Phil Nash
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2018-03-06 00:00:00.000000000 Z
+date: 2018-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -76,6 +76,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -83,9 +84,11 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- lib/locale/en.yml
 - lib/pwned.rb
 - lib/pwned/error.rb
 - lib/pwned/password.rb
+- lib/pwned/pwned_validator.rb
 - lib/pwned/version.rb
 - pwned.gemspec
 homepage: https://github.com/philnash/pwned