pwned 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e197213ac23ae94598dbf91b7a09fadd740db379d5abefdb8ad7c9623d9514b
-  data.tar.gz: 960c6e4ab1d856480dbc236059abea531dc747f4a1d59a7e7db52534c2958866
+  metadata.gz: 4661790082f543ba897baf211da660c7a4f654444121f4ff3ba08542c08c412b
+  data.tar.gz: f52a3f3cf36d461e8704a632f97829a5d9f871d9916a55687d4a0b2156b44b75
 SHA512:
-  metadata.gz: dede2324974438b89612b443e50c8d7c06fe9b35d3e5c6f36661ad73d28513ebb62eedbc60f0a72d346c935141b96f30b98a6ad21cb2950f45a418c76d33c6b1
-  data.tar.gz: 32a0659ce0a7b80967ebf68809bf5881623f473ab561dfcba9f131eb86af60b9f0cb4031603c85c295d37f9d7aae10ce03ae3a580c3cc437c486cff099a4f962
+  metadata.gz: c114c3ca6e7667d1760ad2ae5dabcc7bf8d14b91e42788f7e36bba716eecd9bef6e1847e93dd12df4f8afed19460d26a068dc22ffb2270ceef8dc342f81690e0
+  data.tar.gz: c19d20d765cd57e64468c27a3e8f134e53d8f6e9ae22497c2d94a315a584e2e19b1913d47b37e89c9525ce80d85d10d43437a623d211766aa7242dbe1144e906

data/.travis.yml

@@ -3,21 +3,25 @@ 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
+    - RAILS_VERSION=4.2.11.1
+    - RAILS_VERSION=5.0.7.2
+    - RAILS_VERSION=5.1.7
+    - RAILS_VERSION=5.2.3
+    - RAILS_VERSION=6.0.0
 
 rvm:
-  - 2.5.0
-  - 2.4.0
-  - 2.3.0
+  - 2.7
+  - 2.6
+  - 2.5
+  - 2.4
   - jruby
   - ruby-head
 
-before_install: gem install bundler -v 1.16.1
+before_install: gem install bundler
 
 matrix:
   allow_failures:
     - rvm: ruby-head
-    - env: RAILS_VERSION=5.2.0.rc1
+  exclude:
+    - rvm: 2.4
+      env: RAILS_VERSION=6.0.0

data/.yardopts

@@ -0,0 +1 @@
+--output-dir docs

data/CHANGELOG.md

@@ -1,26 +1,81 @@
 # Changelog for `Pwned`
 
-## Ongoing [☰](https://github.com/philnash/pwned/compare/v1.1.0...master)
+## Ongoing [☰](https://github.com/philnash/pwned/compare/v2.0.2...master)
 
-...
+## 2.1.0 (July 8, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.2...v2.1.0)
 
-## 1.2.0 (March 15, 2018) [☰](https://github.com/philnash/pwned/commits/v1.2.0)
+- Minor updates
 
-* Major updates
-  * Changes `PwnedValidator` to `NotPwnedValidator`, so that the validation looks like `validates :password, not_pwned: true`. `PwnedValidator` now subclasses `NotPwnedValidator` for backwards compatibility with version 1.1.0 but is deprecated.
+  - Adds `Pwned::HashedPassword` class which is initializd with a SHA1 hash to
+    query the API with so that the lookup can be done in the background without
+    storing passwords. Fixes #19, thanks [@paprikati](https://github.com/paprikati).
 
-## 1.1.0 (March 12, 2018) [☰](https://github.com/philnash/pwned/commits/v1.1.0)
+## 2.0.2 (May 20, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.1...v2.0.2)
 
-* 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 fix
 
-* 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))
+  - It was found to be possible for reading the lines body of a response to
+    result in a `nil` which caused trouble with string concatenation. This
+    avoids that scenario. Fixes #18, thanks [@flori](https://github.com/flori).
+
+## 2.0.1 (January 14, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.0...v2.0.1)
+
+- Minor updates
+
+  - Adds double-splat to ActiveModel::Errors#add calls with options to make Ruby 2.7 happy.
+  - Detects presence of Net::HTTPClientException in tests to remove deprecation warning.
+
+## 2.0.0 (October 1, 2019) [☰](https://github.com/philnash/pwned/compare/v1.2.1...v2.0.0)
+
+- Major updates
+
+  - Switches from `open-uri` to `Net::HTTP`. This is a potentially breaking change.
+  - `request_options` are now used to configure `Net::HTTP.start`.
+  - Rather than using all string keys from `request_options`, HTTP headers are now
+    specified in their own `headers` hash. To upgrade, any options intended as
+    headers need to be extracted into a `headers` hash, e.g.
+
+    ```diff
+      validates :password, not_pwned: {
+    -    request_options: { read_timeout: 5, open_timeout: 1, "User-Agent" => "Super fun user agent" }
+    +    request_options: { read_timeout: 5, open_timeout: 1, headers: { "User-Agent" => "Super fun user agent" } }
+      }
+
+    -  password = Pwned::Password.new("password", 'User-Agent' => 'Super fun new user agent')
+    +  password = Pwned::Password.new("password", headers: { 'User-Agent' => 'Super fun new user agent' }, read_timeout: 10)
+    ```
+
+  - Adds a CLI to let you check passwords on the command line
+
+    ```bash
+    $ pwned password
+    Pwned!
+    The password has been found in public breaches 3730471 times.
+    ```
+
+## 1.2.1 (March 17, 2018) [☰](https://github.com/philnash/pwned/compare/v1.2.0...v1.2.1)
+
+- Minor updates
+  - Validator no longer raises `TypeError` when password is `nil`
+
+## 1.2.0 (March 15, 2018) [☰](https://github.com/philnash/pwned/compare/v1.1.0...v1.2.0)
+
+- Major updates
+  - Changes `PwnedValidator` to `NotPwnedValidator`, so that the validation looks like `validates :password, not_pwned: true`. `PwnedValidator` now subclasses `NotPwnedValidator` for backwards compatibility with version 1.1.0 but is deprecated.
+
+## 1.1.0 (March 12, 2018) [☰](https://github.com/philnash/pwned/compare/v1.0.0...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)
 

data/README.md

@@ -2,9 +2,32 @@
 
 An easy, Ruby way to use the Pwned Passwords API.
 
-[![Gem Version](https://badge.fury.io/rb/pwned.svg)](https://rubygems.org/gems/pwned) [![Build Status](https://travis-ci.org/philnash/pwned.svg?branch=master)](https://travis-ci.org/philnash/pwned) [![Maintainability](https://codeclimate.com/github/philnash/pwned/badges/gpa.svg)](https://codeclimate.com/github/philnash/pwned/maintainability)
-
-[API docs](https://philnash.github.io/pwned/) | [GitHub repo](https://github.com/philnash/pwned)
+[![Gem Version](https://badge.fury.io/rb/pwned.svg)](https://rubygems.org/gems/pwned) [![Build Status](https://travis-ci.org/philnash/pwned.svg?branch=master)](https://travis-ci.org/philnash/pwned) [![Maintainability](https://codeclimate.com/github/philnash/pwned/badges/gpa.svg)](https://codeclimate.com/github/philnash/pwned/maintainability) [![Inline docs](https://inch-ci.org/github/philnash/pwned.svg?branch=master)](https://inch-ci.org/github/philnash/pwned)
+
+[API docs](https://www.rubydoc.info/gems/pwned) | [GitHub repo](https://github.com/philnash/pwned)
+
+## Table of Contents
+
+- [Pwned](#pwned)
+  - [Table of Contents](#table-of-contents)
+  - [About](#about)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Plain Ruby](#plain-ruby)
+      - [Advanced](#advanced)
+    - [ActiveRecord Validator](#activerecord-validator)
+      - [I18n](#i18n)
+      - [Threshold](#threshold)
+      - [Network Error Handling](#network-error-handling)
+      - [Custom Request Options](#custom-request-options)
+    - [Using Asynchronously](#using-asynchronously)
+    - [Devise](#devise)
+    - [Command line](#command-line)
+  - [How Pwned is Pi?](#how-pwned-is-pi)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
 
 ## About
 
@@ -14,6 +37,8 @@ Troy Hunt's [Pwned Passwords API V2](https://haveibeenpwned.com/API/v2#PwnedPass
 
 The data from this API is provided by [Have I been pwned?](https://haveibeenpwned.com/). Before using the API, please check [the acceptable uses and license of the API](https://haveibeenpwned.com/API/v2#AcceptableUse).
 
+Here is a blog post I wrote on [how to use this gem in your Ruby applications to make your users' passwords better](https://www.twilio.com/blog/2018/03/better-passwords-in-ruby-applications-pwned-passwords-api.html).
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -32,6 +57,14 @@ Or install it yourself as:
 
 ## Usage
 
+There are a few ways you can use this gem:
+
+1. [Plain Ruby](#plain-ruby)
+2. [Rails](#activerecord-validator)
+3. [Rails and Devise](#devise)
+
+### Plain Ruby
+
 To test a password against the API, instantiate a `Pwned::Password` object and then ask if it is `pwned?`.
 
 ```ruby
@@ -72,10 +105,11 @@ Pwned.pwned_count("password")
 
 #### 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).
+You can set http request options to be used with `Net::HTTP.start` when making the request to the API. These options are
+documented in the [`Net::HTTP.start` documentation](http://ruby-doc.org/stdlib-2.6.3/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start). The `:headers` option defines defines HTTP headers. These headers must be string keys.
 
 ```ruby
-password = Pwned::Password.new("password", { 'User-Agent' => 'Super fun new user agent' })
+password = Pwned::Password.new("password", headers: { 'User-Agent' => 'Super fun new user agent' }, read_timeout: 10)
 ```
 
 ### ActiveRecord Validator
@@ -113,7 +147,7 @@ class User < ApplicationRecord
 end
 ```
 
-#### Network Errors Handling
+#### Network Error 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:
 
@@ -145,17 +179,112 @@ 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"`):
+You can configure network requests made from the validator using `:request_options` (see [Net::HTTP.start](http://ruby-doc.org/stdlib-2.6.3/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start) for the list of available options).
+In addition to these options, HTTP headers can be specified with the `:headers` key, e.g. `"User-Agent"`):
 
 ```ruby
   validates :password, not_pwned: {
-    request_options: { read_timeout: 5, open_timeout: 1, "User-Agent" => "Super fun user agent" }
+    request_options: { read_timeout: 5, open_timeout: 1, headers: { "User-Agent" => "Super fun user agent" } }
   }
 ```
 
-## TODO
+### Using Asynchronously
+
+You may have a use case for hashing the password in advance, and then making the call to the Pwned api later
+(for example if you want to enqueue a job without storing the plaintext password):
+
+```ruby
+hashed_password = Pwned.hash_password(password)
+# some time later
+Pwned::HashPassword.new(hashed_password, request_options).pwned?
+```
+
+### Devise
+
+If you are using Devise I recommend you use the [devise-pwned_password extension](https://github.com/michaelbanfield/devise-pwned_password) which is now powered by this gem.
+
+### Command line
+
+The gem provides a command line utility for checking passwords. You can call it from your terminal application like this:
+
+```bash
+$ pwned password
+Pwned!
+The password has been found in public breaches 3645804 times.
+```
+
+If you don't want the password you are checking to be visible, call:
 
-- [ ] Devise plugin
+```bash
+$ pwned --secret
+```
+
+You will be prompted for the password, but it won't be displayed.
+
+## How Pwned is Pi?
+
+[@daz](https://github.com/daz) [shared](https://twitter.com/dazonic/status/1074647842046660609) a fantastic example of using this gem to show how many times the digits of Pi have been used as passwords and leaked.
+
+```ruby
+require 'pwned'
+
+PI = '3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111'
+
+for n in 1..40
+  password = Pwned::Password.new PI[0..(n + 1)]
+  str = [ n.to_s.rjust(2) ]
+  str << (password.pwned? ? '😡' : '😃')
+  str << password.pwned_count.to_s.rjust(4)
+  str << password.password
+
+  puts str.join ' '
+end
+```
+
+The results may, or may not, surprise you.
+
+```
+ 1 😡   16 3.1
+ 2 😡  238 3.14
+ 3 😡   34 3.141
+ 4 😡 1345 3.1415
+ 5 😡 2552 3.14159
+ 6 😡  791 3.141592
+ 7 😡 9582 3.1415926
+ 8 😡 1591 3.14159265
+ 9 😡  637 3.141592653
+10 😡  873 3.1415926535
+11 😡  137 3.14159265358
+12 😡  103 3.141592653589
+13 😡   65 3.1415926535897
+14 😡  201 3.14159265358979
+15 😡   41 3.141592653589793
+16 😡   57 3.1415926535897932
+17 😡   28 3.14159265358979323
+18 😡   29 3.141592653589793238
+19 😡    1 3.1415926535897932384
+20 😡    7 3.14159265358979323846
+21 😡    5 3.141592653589793238462
+22 😡    2 3.1415926535897932384626
+23 😡    2 3.14159265358979323846264
+24 😃    0 3.141592653589793238462643
+25 😡    3 3.1415926535897932384626433
+26 😃    0 3.14159265358979323846264338
+27 😃    0 3.141592653589793238462643383
+28 😃    0 3.1415926535897932384626433832
+29 😃    0 3.14159265358979323846264338327
+30 😃    0 3.141592653589793238462643383279
+31 😃    0 3.1415926535897932384626433832795
+32 😃    0 3.14159265358979323846264338327950
+33 😃    0 3.141592653589793238462643383279502
+34 😃    0 3.1415926535897932384626433832795028
+35 😃    0 3.14159265358979323846264338327950288
+36 😃    0 3.141592653589793238462643383279502884
+37 😃    0 3.1415926535897932384626433832795028841
+38 😃    0 3.14159265358979323846264338327950288419
+39 😃    0 3.141592653589793238462643383279502884197
+40 😃    0 3.1415926535897932384626433832795028841971
+```
 
 ## Development
 

data/bin/pwned

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require "pwned"
+require "optparse"
+require "io/console"
+
+options = {}
+parser = OptionParser.new do |opts|
+  opts.banner = <<-USAGE
+Usage: pwned <password>
+
+Tests a password against the Pwned Passwords API using the k-anonymity model,
+which avoids sending the entire password to the service.opts
+
+If the password has been found in a publicly available breach then this tool
+will report how many times it has been seen. Otherwise the tool will report that
+the password has not been found in a public breach yet.
+
+USAGE
+
+  opts.version = Pwned::VERSION
+
+  opts.on("-s", "--secret", "Enter password without displaying characters.\n#{" "* 37}Overrides provided arguments.")
+  opts.on_tail("-h", "--help", "Show help.")
+  opts.on_tail("-v", "--version", "Show version number.\n\n")
+end
+
+parser.parse!(ARGV, into: options)
+
+if options[:help]
+  puts parser.help
+  exit
+end
+if options[:version]
+  puts parser.ver
+  exit
+end
+password_to_test = ARGV.first
+if options[:secret]
+  password_to_test = STDIN.getpass("Password: ")
+end
+if !password_to_test || password_to_test.strip == ""
+  puts parser.help
+  exit
+end
+password = Pwned::Password.new(password_to_test || ARGV.first)
+if password.pwned?
+  puts "Pwned!\nThe password has been found in public breaches #{password.pwned_count} times."
+else
+  puts "The password has not been found in a public breach."
+end
+

data/lib/pwned.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "digest"
 require "pwned/version"
 require "pwned/error"
 require "pwned/password"
+require "pwned/hashed_password"
 
 begin
   # Load Rails and our custom validator
@@ -29,10 +31,10 @@ module Pwned
   #     Pwned.pwned?("pwned::password") #=> false
   #
   # @param password [String] The password you want to check against the API.
-  # @param [Hash] request_options Options that can be passed to +open+ when
+  # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
   #   calling the API
-  # @option request_options [String] 'User-Agent' ("Ruby Pwned::Password #{Pwned::VERSION}")
-  #   The user agent used when making an API request.
+  # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
+  #   HTTP headers to include in the request
   # @return [Boolean] Whether the password appears in the data breaches or not.
   # @since 1.1.0
   def self.pwned?(password, request_options={})
@@ -47,14 +49,28 @@ module Pwned
   #     Pwned.pwned_count("pwned::password") #=> 0
   #
   # @param password [String] The password you want to check against the API.
-  # @param [Hash] request_options Options that can be passed to +open+ when
+  # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
   #   calling the API
-  # @option request_options [String] 'User-Agent' ("Ruby Pwned::Password #{Pwned::VERSION}")
-  #   The user agent used when making an API request.
+  # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
+  #   HTTP headers to include in the request
   # @return [Integer] The number of times the password has appeared in the data
   #   breaches.
   # @since 1.1.0
   def self.pwned_count(password, request_options={})
     Pwned::Password.new(password, request_options).pwned_count
   end
+
+  ##
+  # Returns the full SHA1 hash of the given password in uppercase. This can be safely passed around your code
+  # before making the pwned request (e.g. dropped into a queue table).
+  #
+  # @example
+  #     Pwned.hash_password("password") #=> 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8
+  #
+  # @param password [String] The password you want to check against the API
+  # @return [String] An uppercase SHA1 hash of the password
+  # @since 2.1.0
+  def self.hash_password(password)
+    Digest::SHA1.hexdigest(password).upcase
+  end
 end