pwned 2.0.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7e2d94dbe8ca81e5e0d8024cb614d2039a4b8cbd835a805131a9d98c8215327
-  data.tar.gz: 73d6a46ff19e904ba94590de3526709183e43956152d048352263c0b4a0246c3
+  metadata.gz: f4b8270eaf162b50ef112371c2e35dd41141dec39e4e11d5a76936119e2ca569
+  data.tar.gz: fdec9b67cc6465fa64062697253e6cf078ddb2b2deb71cf829a919dca7953f48
 SHA512:
-  metadata.gz: 9fc9f07b450fddcc3dff391640bbce98589de8779254d470413111d5198b50ace2c71264f7dd6f81c06caec4262a7be360bb5b6e2dd9699262be72fa0905726f
-  data.tar.gz: f03aec89ab299234ef7823097c4ffd943576019381249aaf097c38e74651ad5b4da1a66136320257729a9442b8a6c68a516b71fae3c2c12c9431ac56c90162c5
+  metadata.gz: 7ec757852674e3e44ac71a71ed5c31d3503b5f0547871f940d56e8e2d8838b0b89e36742c0e10108f1c00fddc54016454d3ba77348cddd7be659d1ed4fdaf71a
+  data.tar.gz: 304b59ce60639f57c7a3a81c5e0f172dc8de9a2128018abe636be7f6d88074af59ac193d2538f86c298d4f8a537b0152bdcab6efb8cf4a27d5c6a13c64b9e311

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: philnash

data/.github/workflows/tests.yml

@@ -0,0 +1,39 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6, 2.7, 3.0, head]
+        rails: [4.2.11.3, 5.0.7.2, 5.1.7, 5.2.4.4, 6.0.3.4, 6.1.0]
+        exclude:
+          # Ruby 3.0 and Rails 5 do not get along together.
+          - ruby: 3.0
+            rails: 5.0.7.2
+          - ruby: 3.0
+            rails: 5.1.7
+          - ruby: 3.0
+            rails: 5.2.4.4
+          - ruby: head
+            rails: 5.0.7.2
+          - ruby: head
+            rails: 5.1.7
+          - ruby: head
+            rails: 5.2.4.4
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') }}
+    env:
+      RAILS_VERSION: ${{ matrix.rails }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: "Install dependencies (rails: ${{matrix.rails}})"
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rspec

data/CHANGELOG.md

@@ -1,8 +1,39 @@
 # Changelog for `Pwned`
 
-## Ongoing [☰](https://github.com/philnash/pwned/compare/v2.0.1...master)
+## Ongoing [☰](https://github.com/philnash/pwned/compare/v2.2.0...master)
 
-## 2.0.1 (January 14, 2019) [☰](https://github.com/philnash/pwned/compare/v2.0.0...v2.0.1)
+## 2.3.0 (August 30, 2021) [☰](https://github.com/philnash/pwned/compare/v2.2.0...v2.3.0)
+
+- Minor updates
+
+  - Restores `Net::HTTP` default behaviour to use environment supplied HTTP
+    proxy
+  - Adds `ignore_env_proxy` to ignore any proxies set in the environment
+
+## 2.2.0 (March 27, 2021) [☰](https://github.com/philnash/pwned/compare/v2.1.0...v2.2.0)
+
+- Minor updates
+
+  - Adds `:proxy` option to `request_options` to directly set a proxy on the
+    request. Fixes #21, thanks [dparpyani](https://github.com/dparpyani).
+
+## 2.1.0 (July 8, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.2...v2.1.0)
+
+- Minor updates
+
+  - 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).
+
+## 2.0.2 (May 20, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.1...v2.0.2)
+
+- Minor fix
+
+  - 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
 

data/README.md

@@ -2,19 +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) [![Inline docs](https://inch-ci.org/github/philnash/pwned.svg?branch=master)](https://inch-ci.org/github/philnash/pwned)
+[![Gem Version](https://badge.fury.io/rb/pwned.svg)](https://rubygems.org/gems/pwned) ![Build Status](https://github.com/philnash/pwned/workflows/tests/badge.svg) [![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://philnash.github.io/pwned/) | [GitHub repo](https://github.com/philnash/pwned)
+[API docs](https://www.rubydoc.info/gems/pwned) | [GitHub repo](https://github.com/philnash/pwned)
 
 ## Table of Contents
 
+* [Table of Contents](#table-of-contents)
 * [About](#about)
 * [Installation](#installation)
 * [Usage](#usage)
   * [Plain Ruby](#plain-ruby)
-  * [Rails (ActiveRecord)](#activerecord-validator)
+    * [Custom request options](#custom-request-options)
+      * [HTTP Headers](#http-headers)
+      * [HTTP Proxy](#http-proxy)
+  * [ActiveRecord Validator](#activerecord-validator)
+    * [I18n](#i18n)
+    * [Threshold](#threshold)
+    * [Network Error Handling](#network-error-handling)
+    * [Custom Request Options](#custom-request-options-1)
+      * [HTTP Headers](#http-headers-1)
+      * [HTTP Proxy](#http-proxy-1)
+  * [Using Asynchronously](#using-asynchronously)
   * [Devise](#devise)
+  * [Rodauth](#rodauth)
   * [Command line](#command-line)
+  * [Unpwn](#unpwn)
 * [How Pwned is Pi?](#how-pwned-is-pi)
 * [Development](#development)
 * [Contributing](#contributing)
@@ -95,13 +108,49 @@ Pwned.pwned_count("password")
 #=> 3303003
 ```
 
-#### Advanced
+#### Custom request options
 
-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.
+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](https://ruby-doc.org/stdlib-3.0.0/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start). For example:
 
 ```ruby
-password = Pwned::Password.new("password", headers: { 'User-Agent' => 'Super fun new user agent' }, read_timeout: 10)
+password = Pwned::Password.new("password", read_timeout: 10)
+```
+
+##### HTTP Headers
+
+The `:headers` option defines defines HTTP headers. These headers must be string keys.
+
+```ruby
+password = Pwned::Password.new("password", headers: {
+  'User-Agent' => 'Super fun new user agent'
+})
+```
+
+##### HTTP Proxy
+
+An HTTP proxy can be set using the `http_proxy` or `HTTP_PROXY` environment variable. This is the same way that `Net::HTTP` handles HTTP proxies if no proxy options are given. See [`URI::Generic#find_proxy`](https://ruby-doc.org/stdlib-3.0.1/libdoc/uri/rdoc/URI/Generic.html#method-i-find_proxy) for full details on how Ruby detects a proxy from the environment.
+
+```ruby
+# Set in the environment
+ENV["http_proxy"] = "https://username:password@example.com:12345"
+
+# Will use the above proxy
+password = Pwned::Password.new("password")
+```
+
+You can specify a custom HTTP proxy with the `:proxy` option:
+
+```ruby
+password = Pwned::Password.new(
+  "password",
+  proxy: "https://username:password@example.com:12345"
+)
+```
+
+If you don't want to set a proxy and you don't want a proxy to be inferred from the environment, set the `:ignore_env_proxy` key:
+
+```ruby
+password = Pwned::Password.new("password", ignore_env_proxy: true)
 ```
 
 ### ActiveRecord Validator
@@ -171,18 +220,81 @@ end
 
 #### Custom Request Options
 
-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"`):
+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). 
+
+```ruby
+  validates :password, not_pwned: {
+    request_options: {
+      read_timeout: 5,
+      open_timeout: 1
+    }
+  }
+```
+
+In addition to these options, you can also set the following:
+
+##### HTTP Headers
+
+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, headers: { "User-Agent" => "Super fun user agent" } }
+    request_options: {
+      headers: { "User-Agent" => "Super fun user agent" }
+    }
   }
 ```
 
+##### HTTP Proxy
+
+An HTTP proxy can be set using the `http_proxy` or `HTTP_PROXY` environment variable. This is the same way that `Net::HTTP` handles HTTP proxies if no proxy options are given. See [`URI::Generic#find_proxy`](https://ruby-doc.org/stdlib-3.0.1/libdoc/uri/rdoc/URI/Generic.html#method-i-find_proxy) for full details on how Ruby detects a proxy from the environment.
+
+```ruby
+  # Set in the environment
+  ENV["http_proxy"] = "https://username:password@example.com:12345"
+
+  validates :password, not_pwned: true
+```
+
+You can specify a custom HTTP proxy with the `:proxy` key:
+
+```ruby
+  validates :password, not_pwned: {
+    request_options: {
+      proxy: "https://username:password@example.com:12345"
+    }
+  }
+```
+
+If you don't want to set a proxy and you don't want a proxy to be inferred from the environment, set the `:ignore_env_proxy` key:
+
+```ruby
+  validates :password, not_pwned: {
+    request_options: {
+      ignore_env_proxy: true
+    }
+  }
+```
+
+### Using Asynchronously
+
+You may have a use case for hashing the password in advance, and then making the call to the Pwned Passwords API later (for example if you want to enqueue a job without storing the plaintext password). To do this, you can hash the password with the `Pwned.hash_password` method and then initialize the `Pwned::HashPassword` class with the hash, like this:
+
+```ruby
+hashed_password = Pwned.hash_password(password)
+# some time later
+Pwned::HashPassword.new(hashed_password, request_options).pwned?
+```
+
+The `Pwned::HashPassword` constructor takes all the same options as the regular `Pwned::Password` contructor.
+
 ### 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.
+If you are using [Devise](https://github.com/heartcombo/devise) I recommend you use the [devise-pwned_password extension](https://github.com/michaelbanfield/devise-pwned_password) which is now powered by this gem.
+
+### Rodauth
+
+If you are using [Rodauth](https://github.com/jeremyevans/rodauth) then you can use the [rodauth-pwned](https://github.com/janko/rodauth-pwned) feature which is powered by this gem.
 
 ### Command line
 
@@ -202,6 +314,10 @@ $ pwned --secret
 
 You will be prompted for the password, but it won't be displayed.
 
+### Unpwn
+
+To cut down on unnecessary network requests, [the unpwn project](https://github.com/indirect/unpwn) uses a list of the top one million passwords to check passwords against. Only if a password is not included in the top million is it then checked against the Pwned Passwords API.
+
 ## 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.

data/bin/pwned

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 
-require 'pwned'
-require 'optparse'
-require 'io/console'
+require "pwned"
+require "optparse"
+require "io/console"
 
 options = {}
 parser = OptionParser.new do |opts|

data/lib/pwned/hashed_password.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "pwned/password_base"
+
+module Pwned
+  ##
+  # This class represents a hashed password. It does all the work of talking to the
+  # Pwned Passwords API to find out if the password has been pwned.
+  # @see https://haveibeenpwned.com/API/v2#PwnedPasswords
+  class HashedPassword
+    include PasswordBase
+    ##
+    # Creates a new hashed password object.
+    #
+    # @example A simple password with the default request options
+    #     password = Pwned::HashedPassword.new("ABC123")
+    # @example Setting the user agent and the read timeout of the request
+    #     password = Pwned::HashedPassword.new("ABC123", headers: { "User-Agent" => "My user agent" }, read_timout: 10)
+    #
+    # @param hashed_password [String] The hash of the password you want to check against the API.
+    # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
+    #   calling the API
+    # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
+    #   HTTP headers to include in the request
+    # @option request_options [Symbol] :ignore_env_proxy (false) The library
+    #   will try to infer an HTTP proxy from the `http_proxy` environment
+    #   variable. If you do not want this behaviour, set this option to true.
+    # @raise [TypeError] if the password is not a string.
+    # @since 2.1.0
+    def initialize(hashed_password, request_options={})
+      raise TypeError, "hashed_password must be of type String" unless hashed_password.is_a? String
+      @hashed_password = hashed_password.upcase
+      @request_options = Hash(request_options).dup
+      @request_headers = Hash(request_options.delete(:headers))
+      @request_headers = DEFAULT_REQUEST_HEADERS.merge(@request_headers)
+      @request_proxy = URI(request_options.delete(:proxy)) if request_options.key?(:proxy)
+      @ignore_env_proxy = request_options.delete(:ignore_env_proxy) || false
+    end
+  end
+end

data/lib/pwned/password.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "digest"
-require 'net/http'
+require "pwned/password_base"
 
 module Pwned
   ##
@@ -9,27 +8,7 @@ module Pwned
   # Pwned Passwords API to find out if the password has been pwned.
   # @see https://haveibeenpwned.com/API/v2#PwnedPasswords
   class Password
-    ##
-    # The base URL for the Pwned Passwords API
-    API_URL = "https://api.pwnedpasswords.com/range/"
-
-    ##
-    # The number of characters from the start of the hash of the password that
-    # are used to search for the range of passwords.
-    HASH_PREFIX_LENGTH = 5
-
-    ##
-    # The total length of a SHA1 hash
-    SHA1_LENGTH = 40
-
-    ##
-    # The default request headers that are used to make HTTP requests to the
-    # API. A user agent is provided as requested in the documentation.
-    # @see https://haveibeenpwned.com/API/v2#UserAgent
-    DEFAULT_REQUEST_HEADERS = {
-      "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}"
-    }.freeze
-
+    include PasswordBase
     ##
     # @return [String] the password that is being checked.
     # @since 1.0.0
@@ -46,115 +25,22 @@ module Pwned
     # @param password [String] The password you want to check against the API.
     # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
     #   calling the API
-    # @option request_options [Symbol] :headers ({ "User-Agent" => '"Ruby Pwned::Password #{Pwned::VERSION}" })
+    # @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.
+    # @option request_options [Symbol] :ignore_env_proxy (false) The library
+    #   will try to infer an HTTP proxy from the `http_proxy` environment
+    #   variable. If you do not want this behaviour, set this option to true.
     # @raise [TypeError] if the password is not a string.
     # @since 1.1.0
     def initialize(password, request_options={})
       raise TypeError, "password must be of type String" unless password.is_a? String
       @password = password
+      @hashed_password = Pwned.hash_password(password)
       @request_options = Hash(request_options).dup
       @request_headers = Hash(request_options.delete(:headers))
       @request_headers = DEFAULT_REQUEST_HEADERS.merge(@request_headers)
+      @request_proxy = URI(request_options.delete(:proxy)) if request_options.key?(:proxy)
+      @ignore_env_proxy = request_options.delete(:ignore_env_proxy) || false
     end
-
-    ##
-    # Returns the full SHA1 hash of the given password in uppercase.
-    # @return [String] The full SHA1 hash of the given password.
-    # @since 1.0.0
-    def hashed_password
-      @hashed_password ||= Digest::SHA1.hexdigest(password).upcase
-    end
-
-    ##
-    # @example
-    #     password = Pwned::Password.new("password")
-    #     password.pwned? #=> true
-    #
-    # @return [Boolean] +true+ when the password has been pwned.
-    # @raise [Pwned::Error] if there are errors with the HTTP request.
-    # @raise [Pwned::TimeoutError] if the HTTP request times out.
-    # @since 1.0.0
-    def pwned?
-      pwned_count > 0
-    end
-
-    ##
-    # @example
-    #     password = Pwned::Password.new("password")
-    #     password.pwned_count #=> 3303003
-    #
-    # @return [Integer] the number of times the password has been pwned.
-    # @raise [Pwned::Error] if there are errors with the HTTP request.
-    # @raise [Pwned::TimeoutError] if the HTTP request times out.
-    # @since 1.0.0
-    def pwned_count
-      @pwned_count ||= fetch_pwned_count
-    end
-
-    private
-
-    attr_reader :request_options, :request_headers
-
-    def fetch_pwned_count
-      for_each_response_line do |line|
-        next unless line.start_with?(hashed_password_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 for_each_response_line(&block)
-      begin
-        with_http_response "#{API_URL}#{hashed_password_prefix}" do |response|
-          response.value # raise if request was unsuccessful
-          stream_response_lines(response, &block)
-        end
-      rescue Timeout::Error => e
-        raise Pwned::TimeoutError, e.message
-      rescue => e
-        raise Pwned::Error, e.message
-      end
-    end
-
-    def hashed_password_prefix
-      hashed_password[0...HASH_PREFIX_LENGTH]
-    end
-
-    def hashed_password_suffix
-      hashed_password[HASH_PREFIX_LENGTH..-1]
-    end
-
-    # Make a HTTP GET request given the url and headers.
-    # Yields a `Net::HTTPResponse`.
-    def with_http_response(url, &block)
-      uri = URI(url)
-
-      request = Net::HTTP::Get.new(uri)
-      request.initialize_http_header(request_headers)
-      request_options[:use_ssl] = true
-
-      Net::HTTP.start(uri.host, uri.port, request_options) do |http|
-        http.request(request, &block)
-      end
-    end
-
-    # Stream a Net::HTTPResponse by line, handling lines that cross chunks.
-    def stream_response_lines(response, &block)
-      last_line = ''
-
-      response.read_body do |chunk|
-        chunk_lines = (last_line + chunk).lines
-        # This could end with half a line, so save it for next time
-        last_line = chunk_lines.pop
-        chunk_lines.each(&block)
-      end
-      yield last_line
-    end
-
   end
 end